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System Requirements 



Disk dr ive (s) 

One disk drive if and only if output is sent to the 
same physical disk from which the input was taken. 
None of the programs allows time to swap disks 
•during operation on a one-drive configuration. 
Therefore, two disk drives is a more practical 
configuration. 



For more information about other Microsoft products, 
contact: 

Microsoft Corporation 
10700 Northup Way 
Bellevue, WA 98004 
(206) 828-8080 
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GENERAL INTRODUCTION 



The Microsoft (R) MS (tm)-DOS Programmer 's Reference Manual is 
a technical reference manual for system programmers. This 
manual contains a description and examples of all MS-DOS 2.0 
system calls and interrupts (Chapter 1) . Chapter 2, "MS-DOS 
2.0 Device Drivers" contains information on how to install 
your own device drivers on MS-DOS. Two examples of device 
driver programs (one serial and one block) are included in 
Chapter 2. Chapters 3 through 5 contain technical 
information about MS-DOS, including MS-DOS disk allocation 
(Chapter 3) , MS-DOS control blocks and work areas (Chapter 
4) , and EXE file structure and loading (Chapter 5) . 



CHAPTER 1 
SYSTEM CALLS 



1 . 1 INTRODUCTION 

MS-DOS provides two types of system calls: interrupts and 
function requests. This chapter describes the environments 
from which these routines can be called, how to call them, 
and the processing performed by each. 



1.2 PROGRAMMING CONSIDERATIONS 

The system calls mean you don't have to invent your own watys 
to perform these primitive functions, and make it easier to 
write machine-independent programs. 



1.2.1 Calling From Macro Assembler 

The system calls can be invoked from Macro Assembler simply 
by movinq any required data into reqisters and issuing an 
interrupt. Some of the calls destroy registers, so you may 
have to save registers before using a system call. The 
system calls can be used in macros and procedures to make 
your programs more readable; this technique is used to show 
examples of the calls. 



1.2.2 Calling From A High-Level Language 

The system calls can be invoked from any high-level language 
whose modules can be linked with assembly-language modules. 

Cal ling from M icrosoft B asic ; Different techniques are used 
to invoke system calls from the compiler and interpreter. 
Compiled modules can be linked with assembly-language 
modules; from the interpreter, the CALL statement or USER 
function can be used to execute the appropriate 8086 object 
code . 
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Calling from Microsoft Pascal ; In addition to linking with 
an assembly-language module, Microsoft Pascal includes a 
function (DOSXQQ) that can be used directly from a Pascal 
program to call a function request. 

Calling fro m Microsoft F ORTRAN ; Modules compiled with 
Microsoft FORTRAN can be linked with assembly-language 
modules. 



1.2.3 Returning Control To MS-DOS 

Control can be returned to MS-DOS in any of four ways: 

1. Call Function Request 4CH 

MOV AH , 4CH 
INT 21H 

This is the preferred method. 

2. Call Interrupt 20H: 

INT 20H 



3. Jump to location (the beginning of the Program 
Segment Prefix) : 

JMP 

Location of the Program Segment Prefix contains 
an INT 20H instruction, so this technique is simply 
one step removed from the first. 



4. Call Function Request 00H: 

MOV AH,00H 
INT 21H 

This causes a jump to location 0, so it is simply 
one step removed from technique 2, or two steps 
removed from technique 1. 
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1.2.4 Console And Printer Input/Output Calls 

The console and printer system calls let you read from and 
write to the console device and print on the printer without 
using any machine-specific codes. You can still take 
advantage of specific capabilities (display attributes such 
as positioning the cursor or erasing the screen, printer 
attributes such as double-strike or underline, etc.) by 
using constants for these codes and reassembling once with 
the correct constant values for the attributes. 



1.2.5 Disk I/O System Calls 

Many of the system calls that perform disk input and output 
require placing values into or reading values from two 
system control blocks: the File Control Block (FCB) and 
directory entry. 



1.3 FILE CONTROL BLOCK (FCB) 

The Program Segment Prefix includes room for two FCBs at 
offsets 5CH and 6CH. The system call descriptions refer to 
unopened and opened FCBs. An unopened FCB is one that 
contains only a drive specifier and filename, which can 
contain wild card characters (* and ?) . An opened FCB 
contains all fields filled by the Open. File system call 
(Function OFH) . Table 1.1 describes the fields of the FCB. 
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Table 1.1 Fields of File Control Block (FCB) 





Size 


Offset 


Name 


(bytes) 


Hex 


Decimal 


Drive number 


1 


00H 





Filename 


8 


01-08H 


1-8 


Extension 


3 


09-OBH 


9-11 


Current block 


2 


OCH , ODH 


12,13 


Record size 


2 


0EH,0FH 


14,15 


File size 


4 


10-13H 


16-19 


Date of last write 


2 


14H,15H 


20,21 


Time of last write 


2 


16H,17H 


22,23 


Reserved 


8 


18-1FH 


24-31 


Current record 


1 


20H 


32 


Relative record 


4 


21-24H 


33-36 



1.3.1 Fields Of The FCB 

Dr ive Number (offset 00H) : Specifies the disk drive; 1 
means drive A: and 2 means drive B:. If the FCB is to be 
used to create or open a file, this field can be set to to 
specify the default drive; the Open File system call 
Function (OFH) sets the field to the number of the default 
drive. 

F ilename (offset 01H) ; Eight characters, left-aligned and 
padded (if necessary) with blanks. If you specify a 
reserved device name (such as LPTl) , do not put a colon at 
the end. 

Extens ion (offset 09H) : Three characters, left-aligned and 
padded (if necessary) with blanks. This field can be all 
blanks (no extension) . 

Current Block (offset OCH) : Points to the block (group of 
128 records) that contains the current record. This field 
and the Current Record field (offset 20H) make up the record 
pointer. This field is set to by the Open File system 
call. 
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R ecord Size (offset OEH) : The size of a logical record, in 
bytes. Set to 128 by the Open File system call. If the 
record size is not 128 bytes, you must set this field after 
opening the file. 

File Size (offset 10H) ; The size of the file, in bytes. 
The first word of this 4-byte field is the low-order part of 
the size. 



Date of Last Write (offset 14H) ; 
createH or last updated. The 
mapped into two bytes as follows: 

Offset 15H 
|y|y|y|y|y|y|y|m| 

15 9 8 



The date the file was 
year, month, and day are 



Offset 14H 
|m|m|m|d|d|d|d|d| 

5 4 

Time of Last Write (offset 16H) : The time the file was 
created" or last updated. The hour, minutes, and seconds are 
mapped into two bytes as follows: 
Offset 17H 
|h|h|h|h|h|m|m|m| 

15 11 10 



Offset 16H 
| M | M | M | S 
5 4 



S | S | S | S 



Reserved (offset 18H) : These fields are reserved for use by 
MS-DOS. 

Current Record (offset 20H) : Points to one of the 128 
records in the current block. This field and the Current 
Block field (offset OCH) make up the record pointer. This 
field is n ot initialized by the Open File system call. You 
must set it before doing a sequential read or write to the 
fi'le. 



Rela t ive Record (offset 21H) : Points to the currently 
selected record, counting from the beginning of the file 
(starting with 0) . This field is not initialized by the 
Open File system call. You must set it before doing a 
random read or write to the file. If the record size is 
less than 64 bytes, both words of this field are used; if 
the record size is 64 bytes or more, only the first three 
bytes are used. 
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NOTE 

If you use the FCB at offset 
5CH of the Program Segment 
Prefix, the last byte of the 
Relative Record field is the 
first byte of the unformatted 
parameter area that starts at 
offset 80H. This is the 
default Disk Transfer Address. 



1.3.2 Extended FCB 

The Extended File Control Block is used to create or search 
for directory entries of files with special attributes. It 
adds the following 7-byte prefix to the FCB: 



Name 

Flag byte (255, or FFH) 

Reserved 

Attribute byte: 
02H = Hidden file 
04H = System- file 

1.3.3 Directory Entry 

A directory contains one entry for each file on the disk. 
Each entry is 32 bytes; Table 1.2 describes the fields of 
an entry. 

Table 1.2 Fields of Directory Entry 



Name 

Filename 

Extension 

Attributes 

Reserved 



Size 


Offset 


(bytes) 


(Decimal) 


1 


-7 


5 


-6 


1 


-1 



Size 


Offset 


(bytes) 


Hex 


Decimal 


8 


00-07H 


0-7 


3 


08-OAH 


8-10 


1 


OBH 


11 


10 


0C-15H 


12-21 
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Time of last write 


2 


16H,17H 


22,23 


Date of last read 


2 


18H,19H 


24,25 


Reserved 


2 


IAH , 1BH 


26,27 


File size 


4 


1C-1FH 


28-31 



1.3.4 Fields Of The FCB 

Filename (offset 00H) : Eight characters, left-aligned and 
padded (if necessary) with blanks. MS-DOS uses the first 
byte of this field for two special codes: 

00H (0) End of allocated directory 
E5H (229) Free directory entry 

Extension (offset 08M) : Three characters, left-aligned and 
padded (if necessary) with blanks. This field can be all 
blanks (no extension) . 

Attributes (offset ODH) : Attributes of the file: 



Value 






Hex 


Binary 


Dec 


111 


0000 


000. 


1 


2H 


0000 


0010 


2 


04H 


0000 


0100 


4 


07H 


0000" 


0111 


7 


08H 


0000 


1000 


8 


OAH 


0001 


0000 


10 


16H 


0001 


0110 


22 


20H 


0020 


0000 


32 



Meaning 

Read-only 

Hidden 

System 

Changeable with CHGMOD 

Volume-ID 

Directory 

Hard attributes for FINDENTRY 

Archive 



Reserved (offset 0CH) : Reserved for MS-DOS. 

Time of Last Write (offset 16H) : The time the file was 
created or last updated. The hour, minutes, and seconds are 
mapped into two bytes as follows: 

Offset 17H 

|h|h|h|h|h|m|m|m| 
15 ll 10 



Offset 16H 

I M I M | M | S 
5 4 



S | S | S 



Date of Last Write (offset 18H) : The date the file was 
created or last updated. The year, month, and day are 
mapped into two bytes as follows: 
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Offset 19H 
|y|y|y|y|y|y|y|m| 

15 9 8 



Offset 18H 

| M | M | M | D | D | D | D | D | 
5 4 

File Size (offset 1CH) : The size of the file, in bytes. 

The first word of this 4-byte field is the low-order part of 
the size. 
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1.4 SYSTEM CALL DESCRIPTIONS 

Many system calls require that parameters be loaded into one 
or more registers before the call is issued; most calls 
return information in the registers (usually a code that 
describes the success or failure of the operation). The 
description of. system calls 00H-2EH includes the following: 

A drawing of the 8088 registers that shows their 
contents before and after the system call. 

A more complete description of the register 
contents required before the system call. 

A description of the processing performed. 

A more complete description of the register 
contents after the system call. 

An example of its use. 

The description of system calls 2PH-57H includes the 
following: 

A drawing of the 8088 registers that shows their 
contents before and after the system call. 

A more complete description of the register 
contents required before the system call. 

A description of the processing performed. 

Error returns from the system call. 

An example of its use. 

Figure 1 is an example of how each system call is described. 
Function 27H, Random Block Read, is shown. 
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BX 

CX 

ox 



AH 


AL 


BH 


BL 


CH 


CL 


OH 


DL 



FLAGS'* I FLAGSl 



Call 

AH = 27H 
DS:DX 

Opened FCB 
CX 

Number of blocks to read 

Return 

AL 

= Read completed successfully 

1 = EOF 

2 = End of segment 

3 = EOF, partial record 
CX 

Number of blocks read 



Figure 1 



Example of System Call Description 



1.4.1 Programming Examples 

A macro is defined for each system call, then used in some 
examples. In addition, a few other macros are defined for 
use in the examples. The use of macros allows the examples 
to be more complete programs, rather than isolated uses of 
the system calls. All macro definitions are listed at the 
end of the chapter. 

The examples are not intended to represent good programming 
practice. In particular, error checking and good human 
interface design have been sacrificed to conserve space. 
You may, however, find the macros a convenient way to 
include system calls in^your assembly language programs. 

A detailed description of each system call follows. They 
are listed in numeric order ; the interrupts are described 
first, then the function requests. 



NOTE 



Unless otherwise stated, all 

numbers in the system call 

descriptions — both text and 
code — are in hex. 
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1,5 XENIX COMPATIBLE CALLS 



MS-DOS 2.0 supports hierarchical. (i.e., tree-structured) 
directories, similar to those found in the Xenix operating 
system. (For information on tree-structured directories, 
refer to the MS-DOS User's Guide.) 



The following system calls are compatible with 
system: 



the Xenix 



Function 


39H 


Function 


3AH 


Function 


3BH 


Function 


3CH 


Function 


3DH 


Function 


3FH 


Function 


4 OH 


Function 


41H 


Function 


42H 


Function 


43H 


Function 


4411 


Function 


45H 


Function 


46H 


Function 


4BH 


Function 


4CH 


Function 


4DH 



Create Sub-Directory 

Remove a Directory Entry 

Change the Current Directory 

Create a File 

ODen a File 

Read From File/Device 

Write to a File or Device 

Delete a Directory Entry 

Move a File Pointer 

Change Attributes 

I/O Control for Devices 

Duplicate a File Handle 

Force a Duplicate of a Handle 

Load and Execute a Program 

Terminate a Process 

Retrieve Return Code of a Child 



There is no restriction in MS-DOS 2.0 on the depth of a tree 
(the length of the longest path from root to leaf) except in 
the number of allocation units available. The root 
directory will have a fixed number of entries (64 for the 
single-sided disk). For non-root directories, the number of 
files per directory is only limited by the number of 
allocation units available. 



Pre-2.0 disks will appear to MS-DOS 2.0 as having only 
root directory with files in it and no subdirectories. 
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Implementation of the tree structure is simple. The root 
directory is the pre-2.0 directory. Subdirectories of the 
root have a special attribute set indicating that they are 
directories. The subdirectories themselves are files, 
linked through the FAT as usual. Their contents are 
identical in character to the contents of the root 
directory. 

Pre-2.0 programs that use system calls not described in this 
chapter wiil be unable to make use of files in other 
directories. Those files not necessary for the current task 
will be placed in other directories. 

Attributes apply to the tree-structured directories in the 
following manner: 
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Attribute 
volume id 



Meaning/Function 
for files 



read_only 



archive 



hidden/ 
system 



Meaning/Function 
for directories 



Present at the root. Meaningless. 
Only one file may have 
this set. 



directory Meaningless. 



Old fcb-create, new 
Create, new open (for 
write or read/write) 
will fail. 

Set when file is 
written. Set/reset via 
Function 43H. 

Prevents file from 
being found in search 
first/search next. 
Old open will fail. 



Indicates that the 
directory entry is a 
directory. Cannot be 
changed with 43H. 

Meaningless. 



Meaningless. 



Prevents directory 
entry from being 
found. Function 3BH 
will still work. 
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1.6 INTERRUPTS 

MS-DOS reserves interrupts 20H through 3FH for its own use. 
The table of interrupt routine addresses (vectors) is 
maintained in locations 80H-FCH. Table 1.3 lists the 
interrupts in numeric order; Table 1.4 lists the interrupts 
in alphabetic order (of the description). User programs 
should, only issue Interrupts 20H, 21H, 25H, 26H f and 27H. 
(Function Requests 4CH and 31H are the preferred method for 
Interrupts 20H and 27H for versions of MS-DOS that are 2.0 
and higher.) 



NOTE 



Interrupts 22H, 23H, and 24H 
are not interrupts that can be 
issued by user programs; they 
are simply locations where a 
segment and offset address are 
stored. 
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Table 1.3 MS-DOS Interrupts, Numeric Order 



Interru 


ipt 


Hex 


Dec 


20H 


32 


21H 


33 


22H 


34 


23H 


35 


24H 


36 


2 5H 


37 


26H 


38 


27H 


39 



28-40H 40-64 



Description 

Program Terminate 
Function Request 
Terminate Address 
<CTRL-C> Exit Address 
Fatal Error Abort Address 
Absolute Disk Read 
Absolute Disk Write 
Terminate But Stay Resident 
RESERVED — DO NOT USE 



Table 1.4 MS-DOS Interrupts, Alphabetic Order 



Description 

Absolute Disk Read 
Absolute Disk Write 
<CTRL-C> Exit Address 
Fatal Error Abort Address 
Function Request 
Program Terminate 
RESERVED ~ DO NOT USE 
Terminate Address 
Terminate But Stay Resident 



Interrupt 


Hex 


Dec 


25H 


37 


26H 


38 


23H 


35 


24H 


36 


21H 


33 


20H 


32 


28-40H 


40-64 


22H 


34 


27H 


39 
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Program Terminate (Interrupt 20H) 



BX 
CX 
OX. 



AH 


AL 


BH 


BL 


CM 


CL 


OH 


OL 



FLAGSh I PLAGSi 



Call 
CS 

Segment address of Program Segment 

Prefix 



Return 

None 



Interrupt 20H causes the current process to terminate and 
returns control to its parent process. All open file 
handles are closed and the disk cache is cleaned. This 
interrupt is almost always is used in old .COM files for 
termination. 



The CS register must contain the segment address of 
Program Segment Prefix before you call this interrupt. 



the 



The following exit addresses are restored from the Program 
Segment Prefix: 



Exit Address 



Offset 



Program Terminate OAH 
CONTROL-C OEH 

Critical Error 12H 

All file buffers are flushed to disk. 



NOTE 



Close all files that have 
changed in length before 
issuing this interrupt. If a 
changed file is not closed, 
its length is not recorded 
correctly in the directory. 
See Functions 10H and 3EH for 
a description of the Close 
File system calls. 
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Interrupt 20H is provided for compatibility with versions of 
MS-DOS prior to 2.0. New programs should use Function 
Request 4CH , Terminate a Process. 

Macro Definition: terminate macro 

int 20H 
endm 

Example 

;CS must be equal to PSP values given at program start 
; (ES and DS values) 

INT 20H 
;There is no return from this interrupt 



SYSTEM CALLS 



Function Request Page 1-18 



Function Request (Interrupt 21H) 

AX 



ex 

DX 



AH 


Al 


BH 


BL 


GH 


CL 


OH 


Dl 



FLAGSm FLAGSl 



Call 

AH 

Function number 
Other registers as specified in 

individual function 



Return 

As specified in individual function 



The AH register must contain the number of the system 
function. See Section 1.7, "Function Requests," for a 
description of the MS-DOS system functions. 



NOTE 

No macro is defined for this 
interrupt, because all 
function descriptions in this 
chapter that define a macro 
include Interrupt 21H. 



Example 

To call the Get Time function: 

mov ah,2CH ;Get Time is Function 2CH 
int 21H ;THIS INTERRUPT 
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Terminate Address (Interrupt 22H) 
CONTROL-C Exit Address (Interrupt 23H) 
Fatal Error Abort Address (Interrupt 24H) 



These are not true interrupts, but rather storage locations 
for a segment and offset address. The interrupts are issued 
by MS-DOS under the specified circumstance. You can change 
any of these addresses with Function Request 25H (Set 
Vector) if you prefer to write your own interrupt handlers. 

Interrupt 22H — Terminate Address 

When a program terminates, control transfers to the address 
at offset OAH of the Program Segment Prefix. This address 
is copied into the Program Segment Prefix, from the 
Interrupt 22H vector, when the segment is created. 



Interrupt 23H — CONTROL-C Exit Address 

If the user types CONTROL-C during keyboard input or display 
output, control transfers to the INT 23H vector in the 
interrupt table. This address is copied into the Program 
Segment Prefix, from the Interrupt 23H vector, when the 
segment is created. 

If the CONTROL-C routine preserves all registers, it can end 
with an IRET instruction (return from interrupt) to continue 
program execution. When the interrupt occurs, all registers 
are set to the value they had when the original call to 
MS-DOS was made. There are no restrictions on what a 
CONTROL-C handler can do — including MS-DOS function calls 
— so long as the registers are unchanged if IRET is used. 

If Function 09H or OAH (Display String or Buffered Keyboard 
Input) is interrupted by CONTROL-C, the three-byte sequence 
03H-0DH-0AH (ETX-CR-LF) is sent to the display and the 
function resumes at the beginning of the next line. 

If the program creates a new segment and loads a second 
program that changes the CONTROL-C address, termination of 
the second program restores the CONTROL-C address to its 
value before execution of the second program. 
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Interrupt 24H — Fatal Error Abort Address 

If a fatal disk error occurs during execution of one of the 
disk I/O function calls, control transfers to the INT 24H 
vector in the vector table. This address is copied into the 
Program Segment Prefix, from the Interrupt 24H vector, when 
the segment is created. 

BP:SI contains the address of a Device Header Control Block 
from which additional information can be retrieved. 



NOTE 

Interrupt 24H is not issued if 
the failure occurs during 
execution of Interrupt 25H 
(Absolute Disk Read) or 
Interrupt 26H (Absolute Disk 
Write) . These errors are 
usually handled by the MS-DOS 
error routine in COMMAND.COM 
that retries the disk 
operation, then gives the user 
the choice of aborting, 
retrying the operation, or 
ignoring the error. The 
following topics give you the 
information you need about 
interpreting the error codes, 
managing the registers and 
stack, and controlling the 
system's response to the error 
in order to write your own 
error-handling routines. 



Error Codes 

When an error-handling program gains control from Interrupt 
24H, the AX and DI registers can contain codes that describe 
the error. If Bit 7 of AH is 1, the error is either a bad 
image of the File Allocation Table or an error occurred on a 
character device. The device header passed in BP:SI can be 
examined to determine which case exists. If the attribute 
byte high order bit indicates a block device, then the error 
was a bad FAT. Otherwise, the error is on a character 
device. 
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The following are error codes for Interrupt 24H: 



Error Code 


Description 





Attempt to write on write-protected 




disk 


1 


Unknown unit 


2 


Drive not ready 


3 


Unknown command 


4 


Data error 


5 


Bad request structure length 


6 


Seek error 


7 


Unknown media type 


8 


Sector not found 


9 


Printer out of paper 


A 


Write fault 


B 


Read fault 


C 


General failure 



The user stack will be in effect (the first item described 
below is at the top of the stack), and will contain the 
following from top to bottom: 



IP 
CS 
FLAGS 



MS-DOS registers from 
issuing INT 24H 



AX 
BX 
CX 
DX 
SI 
DI 
BP 
DS 
ES 



User registers at time of original 
INT 21H request 



IP 
CS 
FLAGS 



From the original INT 21H 
from the user to MS-DOS 



The registers are set such that if an IRET is 
MS-DOS will respond according to (AL) as follows: 

(AL)=0 ignore the error 
=1 retry the operation 
-2 terminate the program via INT 23H 

Notes: 



executed. 



I. Before giving this routine control for disk errors, 
MS-DOS performs five retries. 
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2. For disk errors, this exit is taken only for errors 
occurring during an Interrupt 21H. It is not used 
for errors during Interrupts 25H or 26H. 

3. This routine is entered in a disabled state. 

4. The SS, SP, DS, ES, BX, CX, and DX registers must 
be preserved. 



This interrupt handler should refrain from using 
MS-DOS funtion calls. If necessary, it may use 
calls 01H through OCH. Use of any other call will 
destroy the MS-DOS stack and will leave MS-DOS in 
an unpredictable state. 



6. The interrupt handler must not change the contents 
of the device header. 



If the interrupt handler will handle errors rather 
than returning to MS-DOS, it should restore the 
application program's registers from the stack, 
remove all but the last three words on the stack, 
then issue an IRET. This will return to the 
program immediately after the INT 21H that 
experienced the error. Note that if this is done, 
MS-DOS will be in an unstable state until a 
function call higher than OCH is issued. 
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Absolute Disk Read (Interrupt 25H) 



BX 

ex 
ox 



AH 


AL 


BH 


at 


CH 


CL 


DM 


04. 



FLAGS** I FUOSt 



Call 

AL 

Drive number 
DS:BX 

Disk Transfer Address 
CX 

Number of sectors 
DX 

Beginning relative sector 



Return 

AL 

Error code if CP«1 
PlagsL 

CP » if successful 

= 1 if not successful 



The registers must contain the following: 

AL Drive number (0=A, 1=B, etc.). 
BX Offset of Disk Transfer Address 

(from segment address in DS) . 
CX Number of sectors to read. 
DX Beginning relative sector. 

This interrupt transfers control to the MS-DOS BIOS. The 
number of sectors specified in CX is read from the disk to 
the Disk Transfer Address. Its requirements and processing 
are identical to Interrupt 26H, except data is read rather 
than written. 



NOTE 

All registers except the 
segment registers are 
destroyed by this call. Be 
sure to save any registers 
your program uses before 
issuing the interrupt. 



The system pushes the flags at the time of the call; they 
are still there upon return. (This is necessary because 
data is passed back in the flags.) Be sure to pop the stack 
upon return to prevent uncontrolled growth. 
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If the disk operation was successful, the Carry Flag (CF) is 
0. If the disk operation was not successful, CF is 1 and AL 
contains the MS-DOS error code (see Interrupt 24H earlier in 
this section for the codes and their meaning) . 

Macro Definition: 



abs disk read 


macro 


disk, buffer ,num_sectors, start 




mov 


al,disk 




mov 


bx, offset buffer 




mov 


ex , num_sec tor s 




mov 


dh, start 




int 


25H 




endm 




Bxaaple 







The following program copies the contents of a single-sided 
disk in drive A: to the disk in drive B:. It uses a buffer 
of 32K bytes: 

prompt db "Source in A, target in B" ,13,10 

db "Any key to start. $" 

start dw 

buffer db 64 dup (512 dup (?)) ;64 sectors 



int_25H: display prompt ;see Function 09H 
readkbd ;see Function 08H 

mov ex, 5 ;copy 5 groups of 

;64 sectors 

copy: push ex ;save the loop counter 

absdiskread 0, buffer, 64, start ;THIS INTERRUPT 
abs_disk_write 1 , buffer ,64 , start ;see INT 26H 
add start, 64 ;do the next 64 sectors 

pop ex ; restore the loop counter 

loop copy 
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Absolute Disk Write (Interrupt 26H) 



BX 

ex 

OX 



AH 


AL 


8M 


N. 


CH 


CL 


DH 


DC 



FLAGSm I ftA<m 



OS 



Call 

AL 

Drive number 
DS-.BX 

Disk Transfer Address 
CX 

Number of sectors 
DX 

Beginning relative sector 



Return 

AL 

Error code if CF = 1 
FLAGSL 

CF = if successful 

1 if not successful 



The registers must contain the following: 

AL Drive number (0=A, 1=B, etc.). 
BX Offset of Disk Transfer Address 

(from segment address in DS) . 
CX Number of sectors to write. 
DX Beginning relative sector. 

This interrupt transfers control to the MS-DOS BIOS. The 
number of sectors specified in CX is written from the Disk 
Transfer Address to the disk. Its requirements and 
processing are identical to Interrupt 25H, except data is 
written to the disk rather than read from it. 



NOTE 

All registers except the 
segment registers are 
destroyed by this call. Be 
sure to save any registers 
your program uses before 
issuing the interrupt. 



The system pushes the flags at the time of the call; they 
are still there upon return. (This is necessary because 
data is passed back in the flags.) Be sure to pop the stack 
upon return to prevent uncontrolled growth. 
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If the disk operation was successful, the Carry Flag (CF) is 
0. If the disk operation was not successful, CF is 1 and AL 
contains the MS-DOS error code (see Interrupt 24H for the 
codes and their meaninq) . 

Macro Definition: 



abs disk write 


macro 


disk, buffer ,num_sectors , start 




mov 


al,disk 




mov 


bx, offset buffer 




mov 


cx,num sectors 




mov 


dh, start 




int 


26H 




endm 




Example 







The followinq proqram copies the contents of a single-sided 
disk in drive A: to the disk in drive B:, verifying each 
write. It uses a buffer of 32K bytes: 



off 
on 



equ 
equ 



prompt db "Source in A, target in B",13,10 

db "Any key to start. $" 
start dw 
buffer db 64 dup (512 dup (?)) ;64 sectors 



int 26H: 



copv: 



display prompt 
readkbd 
verify on 
mov ex, 5 
push ex 
abs_disk_read 
abs_disk_wr ite 
add start, 64 
pop ex 
loop copy 
verifv off 



;see Function 09H 

;see Function 08H 

;see Function 2EH 

;copy 5 groups of 64 sectors 

;save the loop counter 
0, buffer, 64, start ;see INT 25H 
1, buffer ,64, start ;THIS INTERRUPT 

;do the next 64 sectors 

; restore the loop counter 

;see Function 2EH 
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Terminate But Stay Resident (Interrupt 27H) 



BX 
CX 



AH 


AL 


BH 


BL 


CH 


CL 


OH 


OL 



FLAGSh I FLAGSi 



Call 

CS:DX 

First byte following 
last byte of code 



Return 

None 



The Terminate But Stay Resident call is used to make a piece 
of code remain resident in the system after its termination. 
Typically, this call is used in .COM files to allow some 
device-specific interrupt handler to remain resident to 
process asynchronous interrupts. 

DX must contain the offset (from the segment address in CS) 
of the first byte following the last byte of code in the 
program. When Interrupt 27H is executed, the program 
terminates but is treated as an extension of MS-DOS; it 
remains resident and is not overlaid by other programs when 
it terminates. 

This interrupt is provided for compatibility with versions 
of MS-DOS prior to 2.0. New programs should use Function 
31H, Keep Process. 

Macro Definition: stay_resident macro last_instruc 

mov dx, offset last_instruc 
inc dx 
int 27H 
endm 

Example 

;CS must be equal to PSP values given at program start 
? (ES and DS values) 

mov DX, LastAddress 

int 27H 
;There is no return from this interrupt 
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1.7 FUNCTION REQUESTS 

Most of the MS-DOS function calls require input to be passed 
to them in registers. After setting the proper register 
values, the function may be invoked in one of the following 
ways: 

I. Place the function number in AH and execute a long 
call to offset 50H in your Program Segment Prefix. 
Note that programs using this method will not 
operate correctly on versions of MS-DOS that are 
lower than 2.0. 



2. Place the function number in AH and issue Interrupt 
21H. All of the examples in this chapter use this 
method . 



3. An additional method exists for programs that were 
written with different calling conventions. This 
method should be avoided for all new programs. The 
function number is placed in the CL register and 
other registers are set according to the function 
specification. Then, an intrasegment call is made 
to location 5 in the current code segment. That 
location contains a long call to the MS-DOS 
function dispatcher. Register AX is always 
destroyed if this method is used; otherwise, it is 
the same as normal function calls. Note that this 
method is valid only for Function Requests 00H 
through 024H. 



1.7.1 CP/M(R) -Compatible Calling Sequence 

A different sequence can be used for programs that must 
conform to CP/M calling conventions: 

1. Move any required data into the appropriate 
registers (just as in the standard sequence) . 



2. Move the function number into the CL register. 

3. Execute an intrasegment call to location 5 in the 
current code segment. 

This method can only be used with functions 00H through 24H 
that do not pass a parameter in AL. Register AX is always 
destroyed when a function is called in this manner. 
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1.7.2 Treatment Of Registers 

When MS-DOS takes control after a function call, it switches 
to an internal stack. Registers not used to return 
information (except AX) are preserved. The calling 
program's stack must be large enough to accommodate the 
interrupt system — at least 128 bytes in addition to other 
needs . 



IMPORTANT NOTE 

The macro definitions and 
extended example for MS-DOS 
system calls 00H through 2EH 
can be found at the end of 
this chapter. 



Table 1.5 lists the function requests in numeric order; 
Table 1.6 list the function requests in alphabetic order (of 
the description) . 

Table 1.5 MS-DOS Function Requests, Numeric Order 

Function 

Number Function Name 

00H Terminate Program 

01H Read Keyboard and Echo 

02H Display Character 

03H Auxiliary Input 

04H Auxiliary Output 

05H Print Character 

06H Direct Console I/O 

07H Direct Console Input 

08H Read Keyboard 

09H Display String 

OAH Buffered Keyboard Input 

OBH Check Keyboard Status 

OCH Flush Buffer, Read Keyboard 

ODH Disk Reset 

OEH Select Disk 

OFH Open File 

10H Close File 

11H Search for First Entry 

12H Search for Next Entry 

13H Delete File 

14H Sequential Read 

15H Sequential Write 

16H Create File 

17H Rename File 

19H Current Disk 

1AH Set Disk Transfer Address 

21H Random Read 
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2 2H Random Write 

23H File Size 

24H Set Relative Record 

25H Set Vector 

27H Random Block Read 

28H Random Block Write 

29H Parse File Name 

2AH Get. Date 

2BH Set Date 

2CH Get Time 

2DH Set Time 

2EH Set/Reset Verify Flag 

2FH Get Disk Transfer Address 

30H Get DOS Version Number 

31H Keep Process 

33H CONTROL-C Check 

3SH Get Interrupt Vector 

36H Get Disk Free Space 

38H Return Country-Dependent Information 

39H Create Sub-Directory 

3AH Remove a Directory Entry 

3BH Change Current Directory 

3CH Create a File 

3DH Open a File 

3EH Close a File Handle 

3FH Read From File/Device 

40H Write to a File/Device 

41H Delete a Directory Entry 

42H Move a File Pointer 

43H Change Attributes 

44H I/O Control for Devices 

A'iW Duplicate a File Handle 

46H Force a Duplicate of a Handle 

47H Return Text of Current Directory 

48H Allocate Memory 

49H Free Allocated Memory 

4AH Modify Allocated Memory Blocks 

4BH Load and Execute a Program 

4CH Terminate a Process 

4DH Retrieve the Return Code of a Child 

4EH Find Match File 

4FH Step Through a Directory Matching Files 

54H Return Current Setting of Verify 

56H Move a Directory Entry 

57H Get/Set Date/Time of File 
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Table 1.6 MS-DOS Function Requests, Alphabetic Order 

Function Name Number 

Allocate Memory 48H 

Auxiliary Input 03H 

Auxiliary Output 04H 

Buffered Keyboard Input OAH 

Change Attributes 43H 

Change the Current Directory 3BH 

Check Keyboard Status OBH 

Close a File Handle 3EH 

Close File 10H 

CONTROL-C Check 33H 

Create a File 3CH 

Create File 16H 

Create Sub-Directory 39H 

Current Disk 19H 

Delete a Directory Entry 41H 

Delete File 13H 

Direct Console Tnput 07H 

Direct Console I/O 06H 

Disk oeset ODH 

Display Character 02H 

Display String 09H 

Duplicate a File Handle 45H 

File Size 23H 

Find Match File 4EH 

Flush Buffer, Read Keyboard OCH 

Force a Duplicate of a Handle 46H 

Free Allocated Memory 49H 

Get Date 2AH 

Get Disk Free Space 36H 

Get Disk Transfer Address 2FH 

Get DOS Version Number 30H 

Get Interrupt Vector 35H 

Get Time 2CH 

Get/Set Date/Time of File 57H 

I/O Control for Devices 44H 

Keep Process 31H 

Load and Execute a Program 4BH 

Modify Allocated Memory Blocks 4AH 

Move a Directory Entry 56H 

Move a File Pointer 42H 

Open a File 3DH 

Open File OFH 

Parse File Name 29H 

Print Character 05H 

Random FUock Read 27H 

Random Block Write 28H 

Random Read 21H 

Random Wr ite 22H 

Read From File/Device 3FH 

Read Keyboard 08H 

Read Keyboard and Echo 01H 
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Remove a Directory Entry 3AH 

Rename File 17H 
Retrieve the Return Code of a Child 4DH 

Return Current Setting of Verify 54H 
Return Country-Dependent Information 38H 

Return Text of Current Directory 47H 

Search for First Entry 11H 

Search for Next Entry 12H 

Select Disk OEH 

Sequential Read 14H 

Sequential Write 15H 

Set Date 2BH 

Set Disk Transfer Address 1AH 

Set Relative Record 24H 

Set Time 2DH 

Set Vector 25H 

Set/Reset Verify Flag 2EH 

Step Through a Directory Matching 4FH 

Terminate a Process 4CH 

Terminate Program 00H 

Write to a File/Device 40H 
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Terminate Program (Punction 00H) 



AH 


AL 


BH 


Bl 


CM 


CI 


DM 


01 



FLAGSh I FLAGSi 



Call 

AH = 00H 

CS 

Segment address of 
Program Segment Prefix 



Return 

None 



Function 00H is called by Interrupt 20H; it performs the 
same processing. 

The CS register must contain the segment address of the 
Program Segment Prefix before you call this interrupt. 

The following exit addresses are restored from the specified 
offsets in the Program Segment Prefix: 

Program terminate OAH 
CONTROL-C OEH 

Critical error 12H 

All file buffers are flushed to disk. 

Warning: Close all files that have changed in length before 
calling this function. If a changed file is not closed, its 
length is not recorded correctly in the directory. See 
Function 10H for a description of the Close File system 
call. 



Macro Definition: terminate_program macro 

xor ah, ah 
int 21H 
endm 

Example 

;CS must be equal to PSP values given at program start 
; (ES and DS values) 

mov ah , 

int 21H 
;There are no returns from this interrupt 



SYSTEM CALLS 



Read Keyboard/Echo 



Page 1-34 



Read Keyboard and Echo (Function 01H) 



BX 
CX 
OX 



AM 


AL 


BH 


BL 


CH 


CL 


OH 


DL 



FLAGSh I FlAGSi 



Call 

AH = 01H 



Return 

AL 

Character typed 



Function 01H waits for a character to be typed at the 
keyboard, then echos the character to the display and 
returns it in AL. If the character is CONTROL-C, Interrupt 
23H is executed. 



Macro Definition: read kbd and echo 



Example 



macro 

mov ah, 01H 
int 21H 
en dm 



The following program both displays and prints characters as 
they are typed. If RETURN is pressed, the program sends 
Line Feed-Carriage Return to both the display and the 
printer: 



func 01H; 



read kbd and echo 



pr int_char 

cmp 

jne 

pr int_char 

display_char 

jmp 



al 

al,0DH 

funcOlH 

10 

10 

func 01H 



;THIS FUNCTION 
;see Function 05H 
;is it a CR? 
;no, print it 
;see Function 05H 
;see Function 02H 
;get another character 
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Display Character (Punction 02H) 



BX 
CX 
OX 



AH 


AL 


BH 


BL 


CM 


CL 


DH 


M. 



FLAOSm flags* 



Call 

AH = 02H 
DL 

Character to be displayed 

Return 

None 



Function 02H displays the character in DL. If CONTROL-C is 
typed, Interrupt 23H is issued. 



Macro Definition: display_char macro 

mov 
mov 
int 
endm 



character 
dl, character 
ah,02H 
2iH 



Example 

The following program converts lowercase characters to 
uppercase before displaying them: 



func_02H: readkbd 

cmp al,"a" 
jl uppercase 
cmp al,"z" 
jg uppercase 
sub al,20H 

uppercase: display_char al 

jmp func 02H: 



;see Function 08H 

; don't convert 

; don't convert 

; convert to ASCII code 

; f or uppercase 

;THIS FUNCTION 

;get another character 
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Auxiliary Input (Function 03H) 



BX 

CX 



AH • 


AL 


BH 


BL 


CM 


CL 


DM 


DL 



FLAGSh I FLAGSi 



Call 

AH = 03H 



Return 

AL 

Character from auxiliary device 



Function 03H waits for a character from the auxiliary input 
device, then returns the character in AL. This system call 
does not return a status or error code. 

If a CONTROL-C has been typed at console input, Interrupt 
23H is issued. 

Macro Definition: aux_input macro 

mov ah,03H 
int 21H 
endm 



Example 

The following program prints characters as they are received 
from the auxiliary device. It stops printing when an 
end-of-file character (ASCII 26, or CONTROL-Z) is received: 



func 03H: 



continue: 



aux_input 
cmp al , 1AH 
je continue 
print_char al 
jmp func 03H 



;THIS FUNCTION 
;end of file? 
;yes, all done 
;see Function 05H 
;get another character 
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Auxiliary Output (Function 04H) 



BX 

CX 



AH 


AL 


BH 


BL 


CH 


CL 


DH 


«. 



FLAGSm FLAGSl 



Call 

AH » 04H 
DL 

Character for auxiliary device 

Return 
None 



Function 04H sends the character in DL to the auxiliary 
output device. This system call does not return a status or 
error code. 

If a CONTROL-C has been typed at console input, Interrupt 
23H is issued. 

Macro Definition: aux_output macro character 

mov dl, character 
mov ah,04H 
int 21H 
endm 



Bxaaple 

The following program gets a series of strings of up to 80 
bytes from the keyboard, sending each to the auxiliary 
device. It stops when a null string (CR only) is typed: 



string db 



81 dup(?) ;see Function OAH 



func_04H:get_string 80, string ;see Function OAH 

cmp string [1] ,0 ;null string? 

je continue ;yes, all done 
mov ex, word ptr string[l] ;get string length 

mov bx,0 ;set index to 

send it: aux_output string [bx+2] ;THIS FUNCTION 

inc bx ;bump index 

loop send_it ;send another character 

jmp func_04H ?get another string 

continue: . 
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Print Character (Function 05H) 



BX 
CX 
OX 



AH 


Al 


BH 


BL 


CM 


CL 


OH 


ex. 



FLAGSh I FLAG&. 



Call 

AH = 05H 
DL 

Character for printer 



Return 

None 



Function 05H prints the character in DL on the standard 
printer device. If CONTROL-C has been typed at console 
input, Interrupt 23H is issued. 



Macro Definition: 



Bxanple 



print_char macro character 

mov dl, character 
mov ah,05H 
int 21H 
endm 



The following program prints a walking test pattern 
printer. It stops if CONTROL-C is pressed. 



on the 



line_ 


num 


db 







func 


05H: 


mov 


CX, 


60 


start 


_line: 


mov 


bl. 


33 






add 


bl, 


line num 






push 


CX 








m6v 


CX 


80 


print 


it: 


print 


char bl 






mc 


bl 








emp 


bl 


126 






jl 


no 


reset 






mov 


bl, 


33 



print 60 lines 

first printable ASCII 

character (I) 

to offset one character 

save number-of-lines counter 

loop counter for line 

THIS FUNCTION 

move to next ASCII character 

last printable ASCII 

character (~) 

not there yet 

start over with (1) 
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noreset: loop print_it ;print another character 

print_char 13 ;carriage return 

print_char 10 ;line feed 

inc line_num ;to offset 1st char, of line 

pop ex ; restore #-of-lines counter 

loop start_line; ;print another line 
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Direct Console I/O (Function 06H) 



BX 

CX 
DX 



AH 


AL 


BH 


BL 


CH 


CL 


DH 


DC 



FLAGSm I FLAGSl 



Call 

AH = 06H 
DL 

See text 



Return 

AL 

If DL = FFH (255) before call, 
then Zero flag set means AL has 
character from keyboard. 
Zero flag not set means there was 
not a character to get, and AL = 



The processing depends on the value in DL when the function 
is called: 

DL is FFH (255) — If a character has been typed at 
the keyboard, it is returned in AL and the Zero 
flag is 0; if a character has not been typed, the 
Zero flag is 1. 

DL is not FFH — The character in DL is displayed. 



This function does not check for CONTROL-C. 



Macro Definition: dir_console_io macro switch 

mov dl , switch 
mov ah,06H 
int 21H 
endm 
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Direct Console I/O 
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Example 

The following program sets the system clock to and 

continuously displays the time. When any character is 

typed, the display stops changing; when any character is 

typed again, the clock is reset to and the display starts 
again: 



time 


db "00:( 


)0:00.00",13,1 


ten 


db 10 




func 06H: 


set time 


0,0,0,0 


read clock: 


get time 






convert 


ch , ten , time 




convert 


cl , ten, time [ 3 




convert 


dh, ten, time [6 




convert 


dl , ten, time [9 




display 


time 




dir console io FFH 




jne 


stop 




jmp 


read_clock 



Stop: 



readkbd 

jmp func_06H 



$" ;see Function 09H 
;for explanation of $ 



see Function 2DH 
see Function 2CH 
see end of chapter 
see end of chapter 
see end of chapter 
see end of chapter 
see Function 09H 
THIS FUNCTION 
yes, stop timer 
no, keep timer 
running 

see Function 08H 
start over 
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Direct Console Input (Function 07H) 

Call 

_ AH = 07H 

ex ' " 

DX 



AH 


AL 


BH 


BL 


CH 


CI 


OH 


01 



FLAGS* FlAGSl 



Return 

AL 

Character from keyboard 



Function 07H waits for a character to be typed, then returns 
it in AL. This function does not echo the character or 
check for C0NTR0L-C. (For a keyboard input function that 
echoes or checks for C0NTR0L-C, see Functions 01H or 08H.) 



Macro Definition: 



dir_console_input macro 

mov ah,07H 
int 21H 
endm 



Example 

The following program prompts for a password (8 characters 
maximum) and places the characters into a string without 
echoing them: 



password db 8 dup(?) 
prompt db "Password: $' 



;see Function 09H for 
explanation of $ 



func_07H: display prompt 
mov ex, 8 
xor bx , bx 

get_pass: dir_console_input 
emp al,0DH 
je continue 
mov password [bx] ,al 
inc bx 
loop get_pass 

continue: . 



;see Function 09H 

^maximum length of password 

?so BL can be used as index 

?THIS FUNCTION 

;was it a CR? 

jyes, all done 

;no, put character in string 

;bump index 

;get another character 

;BX has length of password+1 
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Read Keyboard (Function 08H) 

Call 

AH = 08H 

ex 

OX 



AH 


AL 


BH 


BL 


CH 


CI 


OH 


OL 



FLAGSm FtAGSt 



Return 

AL 

Character from keyboard 



Function 08H waits for a character to be typed, then returns 
it in AL. If CONTROL-C is pressed, Interrupt 23H is 
executed. This function does not echo the character. (For 
a keyboard input function that echoes the character or 
checks for CONTROL-C, see Function 01H.) 



Macro Definition: read kbd 



macro 

mov ah,08H 

int 

endm 



21H 



Example 

The following program prompts for a password (8 characters 
maximum) and places the characters into a string without 
echoing them: 



password db 8 dup(?) 
prompt db "Password: $' 



;see Function 09H 
;for explanation of $ 



func 08H 



get_pass 



continue 



display prompt 

mov ex, 8 

xor bx,bx 

read_kbd 

emp al,0DH 

je continue 

mov password [bx] ,al 

inc bx 

loop get pass 



;see Function 09H 

;maximum length of password 

;BL can be an index 

;THIS FUNCTION 

;was it a CR? 

;yes, all done 

;no, put char, in string 

;bump index 

;get another character 

;BX has length of password+1 
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AH 


AL 


BH 


BL 


CH 


CL 


DH 


OL 



FLAGSm FLAGSl 



Call 

AH = 09H 
DS:DX 

String to be displayed 



Return 

None 



DX must contain the offset (from the segment address in DS) 
of a string that ends with "$". The string is displayed 
(the $ is not displayed) . 

Macro Definition: display macro string 

mov dx, offset string 
mov ah,09H 
int 21H 
endm 

Example 

The following program displays the hexadecimal code of the 
key that is typed: 

table db "0123456789ABCDEF" 

sixteen db 16 

result db " - 00H" r 13, 10,"$" ;see text for 

explanation of $ 



f unc_09H: read_kbd_and echo ysee Function 01H 

convert al, sixteen, result (3] ;see end of chapter 

display result ;THIS FUNCTION 

jmp func_09H ;do it again 
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Buffered Keyboard Input (Function OAH) 



Call 

AH = OAH 
DS:DX 

Input buffer 

Return 

None 



AH 


Al 


UK 


HI 


' M 


I 


DH 


DC 



I LAd'.v > I ACS 



DX must contain the offset (from the segment address in DS) 
of an input buffer of the following form: 

Byte Contents 

1 Maximum number of characters in buffer, including 
the CR (you must set this value) . 

2 Actual number of characters typed, not counting 
the CR (the function sets this value) . 

3-n Buffer; must be at least as long as the number 
in byte 1. 

This function waits for characters to be typed. Characters 
are read from the keyboard and placed in the buffer 
beginning at the third byte until RETURN is typed. If the 
buffer fills to one less than the maximum, additional 
characters typed are ignored and ASCII 7 (BEL) is sent to 
the display until RETURN is pressed. The string can be 
edited as it is being entered. If CONTROL-C is typed, 
Interrupt 23H is issued. 

The second byte of the buffer is set to the number of 
characters entered (not counting the CR) . 



Macro Definition: get_string macro limit, string 

mov dx, off set string 

mov 

mov 

int 

endm 



string, limit 

ah, OAH 

21H 
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Example 

The following program gets a 16-byte (maximum) string from 
the keyboard and fills a 24-line by 80-character screen with 
it: 



buffer 
max_length 
chars_entered db 
string db 

strings per line dw 



crlf 



label byte 
db ? 



db 



17 dup (?) 


13,10,"$" 



;maximum length 
;number of chars. 
;16 chars + CR 
;how many strings 
; f i t on 1 ine 



func OAH: 



display screen: 
display 1 ine: 



getstring 17, buffer 
xor bx,bx 



mov 
mov 
mov 
cbw 
div 



bl ,chars_entered 
buffer [bx+2] ,"$" 
al,50H 



;THIS FUNCTION 
;so byte can be 
;used as index 
;get string length 
;see Function 09H 
.•columns per line 



chars_entered 
ah ,ah 



;times string fits 

; on line 
xor ah, ah ;clear remainder 

mov str ings_per_line,ax ; save col. counter 
mov ex, 24 ;row counter 

push ex ;save it 

mov ex, str ings_per_line ;get col. counter 
display string rsee Function 09H 
loop display_line 

display crlf ;see Function 09H 

pop ex ?get line counter 

loop display screen ;display 1 more line 
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Check Keyboard Status (Function OBH) 



Call 

AH = OBH 



AH 


AL 


BH 


BL 


CM 


CL 


DM 


PI 



FLAGSh FIAGSi. 



OS 

ss 



Return 

AL 

255 (FFH) = characters in type-ahead 
buffer 

= no characters in type-ahead 
buffer 



Checks whether there are characters in the type-ahead 
buffer. If so, AL returns FFH (255); if not, AL returns 0. 
If CONTROL-C is in the buffer, Interrupt 23H is executed. 



Macro Definition: check kbd status 



macro 

mov ah , OBH 

int 21H 

endm 



Example 

The following program continuously displays the time until 
any key is pressed. 



time 


db 


"00:00:00.00" 


,13,10,"$" 


ten 


db 


10 




func OBH: 


get time 




; see F 



convert ch, ten, time 
convert cl , ten, time [3] 
convert dh , ten , t ime [6] 
convert dl, ten, time [9] 
display time 
check_kbd_status 
cmp al,FFH 
je - all_done 
jmp func OBH 



;see end of chapter 

tsee end of chapter 

rsee end of chapter 

rsee end of chapter 

;see Function 09H 

[THIS FUNCTION 

[has a key been typed? 

;yes, go home 

;no, keep displaying 

t time 
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AH 


AL 


BH 


BL 


CH 


CI 


OH 


DL 



Flush Buffer, Read Keyboard (Function OCH) 



Call 

AH = OCH 

AL 

If 6, 7, 8, or OAH = The 
corresponding function 
is called. 

Any other value = no 
further processing. 



Return 

AL 

= Type-ahead buffer was 
flushed; no other 
processing performed. 



FLAGSm I FLAGSi 



The keyboard type-ahead buffer is emptied. Further 
processing depends on the value in AL when the function is 
called: 



1, 6, 7, 8, or OAH — The corresponding MS-DOS 
function is executed. 



Any other value 
returns 0. 



No further processing; AL 



Macro Definition: flush_and_read_kbd macro switch 

mov al, switch 

mov ah, OCH 

int 21H 
endm 



Exaaple 

The following program both displays and prints characters as 
they are typed. If RETURN is pressed, the program sends 
Carriage Return-Line Feed to both the display and the 
printer. 

;THIS FUNCTION 

•see Function 05H 

; is it a CR? 

;no, print it 

;see Function 05H 

•see Function 02H 

;get another character 



func OCH: 


flush and read kbd 1 




print char al 
cmp al , ODH 
jne func OCH 




print_char 10 
display char 10 
jmp func_0CH 



SYSTEM CALLS 



Disk Reset 



Page 1-49 



Disk Reset (Function ODH) 



AH 


At 


BH 


BL 


CM 


CI 


OH 


DL 



cs 



Call 

AH = ODH 



Return 

None 



Function ODH is used to ensure that the internal buffer 
cache matches the disks in the drives. This function writes 
out dirty buffers (buffers that have been modified) , and 
marks all buffers in the internal cache as free. 

Function ODH flushes all file buffers. It does not update 
directory entries; you must close files that have changed 
to update their directory entries (see Function 10H, Close 
File) . This function need not be called before a disk 
change if all files that changed were closed. It is 
generally used to force a known state of the system; 
CONTROL-C interrupt handlers should call this function. 



Macro Definition: 



disk_reset macro disk 

mov ah , ODH 
int 21H 
endm 



Example 

mov ah , ODH 
int 21H 
;There are no errors returned by this call. 
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Select Disk (Function OEH) 



BX 
CX 
DX 



AH 


AL 


BH 


BL 


CH 


CL 


OH 


OL 



FLAGSh FLAGSl 



Call 

AH = OEH 
DL 

Drive number 
(0 = A: , 1 = B: , etc.) 



Return 

AL 

Number of logical drives 



The drive specified in DL (0 = A: , 1 = B: , etc.) is selected 
as the default disk. The number of drives is returned in 
AL. 



Macro Definition: 



select_disk macro disk 

mov dl r disk[-64] 
mov ah , OEH 
int 21H 
endm 



Example 

The following program selects the drive not currently 
selected in a 2-drive system: 



func_0EH: current_disk 
cmp al,00H 
je select_b 
select_disk "A" 
jmp continue 

select_b: select_disk "B" 

continue: . 



;see Function 19H 
;drive A: selected? 
;yes, select B 
;THIS FUNCTION 

;THIS FUNCTION 
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Open File (Function OFH) 



AH 


AL 


BH 


BL 


CH 


CL 


OH 


Di. 



FUAGSh FlAGSl 



Call 

AH = OFH 
DS : DX 

Unopened FCB 



Return 

AL 

= Directory entry found 

255 (FFH) = No directory entry found 



DX must contain the offset (from the segment address in DS) 
of an unopened File Control Block (FCB). The disk directory 
is searched for the named file. 

If a directory entry for the file is found, AL returns and 
the FCB is filled as follows: 

If the drive code was (default disk) , it is 
changed to the actual disk used (1 = A: , 2 = B: , 
etc.). This lets you change the default disk 
without interfering with subsequent operations on 
this file. 

The Current Block field (offset OCH) is set to 
zero. 

The Record Size (offset OEH) is set to the system 
default of 128. 

The File Size (offset 10H) , Date of Last Write 
(offset 14H) , and Time of Last Write (offset 16H) 
are set from the directory entry. 



Before performing a sequential disk operation on the file, 
you must set the Current Record field (offset 20H) . Before 
performing a random disk operation on the file, you must set 
the Relative Record field (offset 21H) . If the default 
record size (128 byt*»*o is not correct, set it to the 
correct length. 
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If a directory entry for the file is not found, AL 
FFH (255). 



returns 



Macro Definition: open macro fcb 

ntov dx, offset fcb 
mov ah,0FH 
int 21H 
endm 

Example 

The following program prints the file named TEXTFII.E. ASC 
that is on the disk in drive B:. If a partial record is in 
the buffer at end-of-file, the routine that prints the 
partial record prints characters until it encounters an 
end-of-file mark (ASCII 26, or CONTROL-Z): 



fcb 




buffer 


f unc 


OFH: 


read 


line 



print it; 



check more: 



find eof: 



all done: 



db 2,"TEXTFILEASC" 
db 25 dup (?) 
db 128 duo (?) 



set_dta buffer 
open fcb 
readseq fcb, 
cmp al,0 2H 
je alldone 
cmp al,00H 
jg check_more 

mov ex, 128 

xor si, si 

print char buffer [si 



mc 


si 


loop 


pr int_it 


jmp 


read line 


cmp 


al,03H 


jne 


all done 


mov 


ex, 128 


xor 


si ,si 


cmp 


buffer [si] ,26 


je 


all_done 


print 


char buffer Tsil 


inc 


si 


loop 


find eof 


close 


fcb 



see Function 1AH 

THIS FUNCTION 

see Function 14H 

end of file? 

yes , go home 

more to come? 

no, check for partial 

record 

yes, print the buffer 

set index to 

see Function 05H 

bump index 

print next character 

read another record 

part, record to print? 

no 

yes, print it 

set index to 

end-of-file mark? 

yes 

see Function 05H 

bump index to next 

character 

;see Function 10H 
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Close File (Function 10H) 



Cx 
OX 



AH 


AL 


BH 


BL 


CH 


CL 


OH 


DL 



FLAGSh I FLAGSt 



Call 

AH = 10H 
DS:DX 

Opened FCB 



Return 

AL 

= Directory entry found 

FFH (255) a No directory entry found 



DX must contain the offset (to the segment address in DS) of 
an opened FCB. The disk directory is searched for the file 
named in the FCB. This function must be called after a file 
is changed to update the directory entry. 

If a directory entry for the file is found, the location of 
the file is compared with the corresponding entries in the 
FCB. The directory entry is updated, if necessary, to match 
the FCB, and AL returns 0. 

If a directory entry for the file is not found, AL returns 
FFH (255) . 

Macro Definition: close macro feb 

mov dx, offset feb 
mov ah,10H 
int 21H 

endm 



Example 

The following program checks the first byte of the file 
named M0D1.BAS in drive B: to see if it is FFH, and prints 
a message if it is: 



message 
feb 

buffer 



db "Not saved in ASCII format" ,13, 10,"$' 
db 2, "MODI BAS" 
db 25 dup (?) 
db 128 dup (?) 



func 10H: 



set_dta buffer 
open feb 
read seq feb 



;see Function 1AH 
;see Function OFH 
;see Function 14H 
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cmp buffer, FFH ;is first byte FFH? 

jne all_done ;no 

display message ;see Function 09H 

all done: close fcb ;THIS FUNCTION 
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Search for First Entry (Function 11H) 



AH 


AL 


BH 


BL 


CM 


CL 


DH 


01 



*LAGSh FLAGSl 



Call 

AH = 11H 
DS:DX 

Unopened FCB 



Return 

= Directory entry found 

FFH (255) = No directory entry found 



DX must contain the offset (from the segment address in DS) 
of an unopened FCB. The disk directory is searched for the 
first matching name. The name can have the ? wild card 
character to match any character. To search for hidden or 
system files, DX must point to the first byte of the 
extended FCB prefix. 

If a directory entry for the filename in the FCB is found, 
AL returns and an unopened FCB of the same type (normal or 
extended) is created at the Disk Transfer Address. 

If a directory entry for the filename in the FCB is not 
found, AL returns FFH (255). 

Notes: 

If an extended FCB is used, the following search pattern is 
used: 



1. If the FCB attribute is zero, only normal file 
entries are found. Entries for volume label, 
sub-directories, hidden, and system files will not 
be returned. 



If the attribute field is set for hidden or system 
files, or directory entries, it is. to be considered 
as an inclusive search. All normal file entries 
plus all entries matching the specified attributes 
are returned. To look at all directory entries 
except the volume label, the attribute byte may be 
set to hidden + system + directory (all 3 bits on) . 
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3. If the attribute field is set for the volume label, 
it is considered an exclusive search, and only the 
volume label entry is returned. 



Macro Definition: 



search_first macro fcb 

mov dx, offset fcb 
mov ah,llH 
int 21H 
endm 



Example 

The following program verifies the existence of a file named 

REPORT. ASM on the disk in drive B:: 

yes db "FILE EXISTS. S" 

no db "FILE DOES NOT EXIST. $" 

fcb db 2, "REPORT ASM" 

db 25 dup (?) 

buffer db 128 dup (?) 



func 11H; 



set_dta buffer 
search first fcb 



cmp 

je 

display 

jmp 
not_there: display 
continue: display 



al,FFH 

not_there 

yes 

continue 

no 

crlf 



;see Function 1AH 

;THIS FUNCTION 

;directory entry found? 

;no 

;see Function 09H 

;see Function 09H 
;see Function 09H 
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Search for Next Entry (Function 12H) 



BX 
CX 
DX 



AH 


Al 


BH 


BL 


CH 


CI 


OH 


OL 



FLAGSh I 



OS 



Call 

AH = 12H 
DS:DX 

Unopened FCB 



Return 

AL 

= Directory entry found 

FFH (255) = No directory entry found 



DX must contain the offset (from the segment address in DS) 
of an FCB previously specified in a call to Function 11H. 
Function 12H is used after Function 11H (Search for First 
Entry) to find additional directory entries that match a 
filename that contains wild card characters. The disk 
directory is searched for the next matching name. The name 
can have the ? wild card character to match any character. 
To search for hidden or system files, DX must point to the 
first byte of the extended FCB prefix. 

If a directory entry for the filename in the FCB is found, 
AL returns and an unopened FCB of the same type (normal or 
extended) is created at the Disk Transfer Address. 



If a directory entry for the filename 
found, AL returns FFH (255). 



in the FCB is not 



Macro Definition: search_next macro fcb 

mov dx, off set fcb 

' mov ah,12H 

int 21H 
endm 

Example 

The following program displays the number of files on the 
disk in drive B: 



message 


db 


"No files", 10, 13, "$ M 


files 


db 





ten 


db 


10 


fcb 


db 


2,"???????????" 




db 


25 dup (?) 


buffer 


db 


128 dup (?) 
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func 12H: 



search dir 



done : 
all done: 



setdta buffer 
search first fcb 
cmp aI,FFH 
je alldone. 
inc files 



search next 
cmp al,FFH 



fcb 



inc 



done 
files 



jmp search dir 



see Function 1AH 

see Function 11H 

directory entry found? 

no, no files on disk 

yes, increment file 

counter 

THIS FUNCTION 

directory entry found? 

no 

yes, increment file 

counter 

check again 



convert files , ten, message ;see end of chapter 
display message ;see Function 09H 
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Delete Pile (Function 13H) 



BX 
CX 
OX 



AH 


AL 


BM 


81 


CH 


CI 


OH 


OL 



FUGSm I FLAGSl 



Call 

AH = 13H 
DS:DX 

Unopened FCB 



Return 

= Directory entry found 

FFH (255) = No directory entry found 



DX must, contain the offset (from the segment address in DS) 
of an unopened FCB. The directory is searched for a 
matching filename. The filename in the FCB can contain the 
? wild card character to match any character. 

If a matching directory entry is found, it is deleted from 
the directory. If the ? wild card character is used in the 
filename, all matching directory entries are deleted. AL 
returns 0. 

If no matching directory entry is found, AL returns FFH 
(255) . 

Macro Definition: delete macro fcb 

mov dx, offset fcb 

mov ah,13H 

int 21H 
endm 

Example 

The following program deletes each file on the disk in drive 
B: that was last written before December 31, 1982: 



year 

month 

day 

files 

ten 

message 



fcb 



dw 
db 
db 
db 
db 
db 



db 
db 



1982 

12 

31 



10 
'NO FILES DELETED." ,13, 10,"$ " 

;see Function 09H for 
explanation of $ 

2,"???????????" 

25 dup (?) 
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buffer 



db 



128 dup (?) 



func J.3H: 


set_ 


dta buffer 




search_first fcb 




cmp 


al,FFH 




je 


all done 


compare : 


convert cfate buffer 




cmp 


ex, year 




jg 


next 




cmp 


dl , month 




J9 


next 




cmp 


dh,day 




jge 


next 




delete buffer 




inc 


files 



next; 



all done: 



search_next fcb 
cmp al,00H 
je compare 
cmp files, 
je all_done 

convert f iles , ten ,mes 
display message 



see Function 1AH 
see Function 11H 
directory entry found? 
no, no files on disk 
see end of chapter 
next several lines 
check date in directory 
entry against date 
above S> check next file 
if date in directory 
entry isn't earlier. 
THIS FUNCTION 
bump deleted-f iles 
counter 

see Function 12H 
directory entry found? 
yes, check date 
any files deleted? 
no, display NO FILES 
message. 

sage ;see end of chapter 

;see Function 09H 
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Sequential Read (Punction 14H) 



AX 
BX 
CX 
OX 



AH 


Ai. 


BH 


BL 


CH 


CI 


OH 


01 



FLAGSh FLAGS). 



Call 

AH = 14H 
DS:DX 

Opened FCB 



Return 

AL 

1 
2 
3 



Read completed successfully 

EOF 

DTA too small 

EOF, partial record 



DX must contain the offset (from the segment address in DS) 
of an opened FCB. The record pointed to by the current 
block (offset OCH) and Current Record (offset 20H) fields is 
loaded at the Disk Transfer Address, then the Current Block 
and Current Record fields are incremented. 

The record size is set to the value at offset OEH in the 
FCB. 

AL returns a code that describes the processing: 

Code Meaning 

Read completed successfully. 

End-of-file, no data in the record. 



Not enough room at the Disk Transfer Address 
to read one record; read canceled. 

3 End-of-file; a partial record was read and 
padded to the record length with zeros. 

Macro Definition: read_seq macro fcb 

mov dx, offset fcb 

mov ah,14H 

int 21H 

endm 
Bxaaple 

The following program displays the file named TEXTFILE.ASC 
that is on the disk in drive B:; its function is similar to 
the MS-DOS TYPE command. If a partial record is in the 
buffer at end of file, the routine that displays the partial 
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record displays characters until it 
end-of-file mark (ASCII 26, or CONTROL-Z): 



encounters 



an 



fcb 




buffer 


f unc 


14H: 


read 


line 



db 2,"TEXTFILEASC" 

db 25 dup (?) 

db 128 dup (?) ,"$" 



set dta buffer 
open fcb 
read seq fc 
cmp " al,02H 
je alldone 
cmp al,0 2H 

jg checkmore 
display buffer 





jmp 


read line 


check more: 


cmp 


al,0 3H 




jne 


all_done 




xor 


si ,si 


find eof: 


cmp 


buffer [ si 1 ,26 




je 


all_done 




displ 


ay_char buffer 




inc 


si 




jmp 


find eof 


all done: 


close 


fcb 



see Function 1AH 

see Function OFH 

THIS FUNCTION 

end-of-file? 

yes 

^nd-of-file with partial 

record? 

yes 

see Function 09H 

get another record 

partial record in buffer? 

no, go home 

set index to 

; is character EOF? 
;yes, no more to display 
(sil ;see Function 02H 
;bump index to next 
;character 

;check next character 
;see Function 10H 
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Sequential Write (Function 15H) 



Call 

AH = 15H 
DS:DX 

Opened FCB 



AH 


AL 


HH 


HI 


CM 


CI 


DM 


DL 



Return 

AL 

00H = Write completed successfully 

01H = Disk full 

2H = DTA too small 



DX must contain the offset (from the segment address in DS) 
of an opened FCB. The record pointed to by. Current Block 
(offc^t- <^H) and Current Record (offset 20H) fields is 
written from the Disk Transfer Address, then the current 
block and current record fields are incremented. 

The record size is set to the value at offset OEH in the 
FCB. If the Record Size is less than a sector, the data at 
the Disk Transfer Address is written to a buffer; the 
buffer is written to disk when it contains a full sector of 
data, or the file is closed, or a Reset Disk system call 
(Function ODH) is issued. 

AL returns a code that describes the processing: 

Code Meaning 

Transfer completed successfully. 

Disk full; write canceled. 



Not enough room at the Disk Transfer Address 
to write one record; write canceled 



»<acro Definition: writeseq macro fcb 

mov dx, offset fcb 

mov ah,15H 

int 21H 
endm 
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Bxaaple 

The following program creates a file named DIR.TMP on the 

disk in drive B: that contains the disk number (0 = A: , 1 » 

B:, etc.) and filename from each directory entry on the 
disk: 



record size 



equ 



14 



;offset of Record Size 
; field in FCB 



fcbl 


db 


2," 


DIR TMP" 


fcb2 


db 
db 


25 
2," 


dup (?) 
'???????????" 


buffer 


db 
db 


25 
126 


dup (?> 
1 dup (?) 


func_15H: 


set_dt2 


i 


buffer 




search_ 


first 


: fcb2 




cmp 
je 




al,FFH 
all done 




create 




fcbl 




mov 




fcbl [record 


writeit: 


write_seq 


fcbl 




search 


next 


fcb2 




cmp 
je 




al,FFH 
all_done 


all done: 


jmp 
close 




write it 
fcbl 



;see Function 1AH 
;see Function 11H 
;directory entry found? 
;no, no files on disk 
;see Function 16H 
_size] , 12 

;set record size to 12 
;THIS FUNCTION 
;see Function 12H 
;directory entry found? 
;no, go home 
;yes, write the record 
•see Function 10H 
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Create Pile (Function 16H) 



AH 


At 


BH 


Bl 


CM 


CL 


DH 


Dt 



FLAGSh [ FLAGSi 



Call 

AH » 16H 

DS:DX 

Unopened FCB 



Return 

AL 

00H = Empty directory found 
FFH (255) * No empty directory 
available 



DX must contain the offset (from the segment address in DS) 
of an unopened FCB. The directory is searched for an empty 
entry or an existing entry for the specified filename. 

If an empty directory entry is found, it is initialized to a 
zero-length file, the Open File system call (Function OFH) 
is called, and AL returns 0. You can create a hidden file 
by using an extended FCB with the attribute byte (offset 
FCB-1) set to 2. 

If an entry is found for the specified filename, all data in 
the file is released, making a zero-length file, and the 
Open File system call (Function OFH) is issued for the 
filename (in other words, if you try to create a file that 
already exists, the existing file is erased, and a new, 
empty file is created) . 

If an empty directory entry is not found and there is no 
entry for the specified filename, AL returns FFH (255) . 

Macro Definition: create macro fcb 

mov dx, offset fcb 
mov ah,16H 
int 21H 
endm 



Example 

The following program creates a file named DIR.TMP on the 

disk in drive B: that contains the disk number (0 = A: , 1 » 

B:, etc.) and filename from each directory entry on the 
disk: 



SYSTEM CALLS Create File Page 1-66 

recordsize equ 14 ;offset of Record Size 

; field of FCB 



fcbl db 2, n DIR TMP" 

db 25 dup (?) 

fcb2 db 2,"???????????" 

db 25 dup (?) 

buffer db 128 dup (?) 



func 16H: set_dta buffer ;see Function 1AH 

searchfirst fcb2 ;see Function 11H 

cmp al,FFH ;directory entry found? 

je all_done ;no, no files on disk 

create fcbl ;THIS FUNCTION 
mov fcbl [record_size] , 12 

;set record size to 12 

write it: write seq fcbl ;see Function 15H 

searcfi_next fcb2 ;see Function 12H 

cmp al,FFH ;directory entry found? 

je all_done ;no, go home 

jmp write_it ?yes, write the record 

all done: close fcbl ;see Function 10H 
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Rename Pile (Function 17H) 



AH 


AL 


DH 


HI 


CH 


CI 


OH 


DL 



E 



HAGS" FLAG! 



Call 

AH = 17H 
DS:DX 

Modified FCB 



Return 

AL 

00H = Directory entry found 
FFH (255) = No directory entry 
found or destination already 
exists 



DX must contain the offset (from the segment address in DS) 
of an FCB with the drive number and filename filled in, 
followed by a second filename at offset 11H. The disk 
directory is searched for an entry that matches the first 
filename, which can contain the ? wild card character. 

If a matching directory entry is found, the filename in the 
directory entry is changed to match the second filename in 
the modified FCB (the two filenames cannot be the same 
name) . Tf the ? wild card character is used in the second 
filename, the corresponding characters in the filename of 
the directory entry are not changed. AL returns 0. 

If a matching directory entry is not found or an entry is 
found for the second filename, AL returns FFH (255). 

Macro Definition: rename macro fcb,newname 

mov dx, offset fcb 

mov ah,17H 

int 21H 
endm 



Example 

The following program prompts for the name of a file 
new name, then renames the file: 



and 



fcb 

promptl 

prompt2 

reply 

crlf 



db 37 dup. (?) 

db "Filename: $" 

db "New name: $" 

db 17 dup(?) 

db 13,10,"$" 
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func 17H: 



display promptl 

get_string 15, reply 

display crlf 

parse reply[2],fcb 

display prompt2 

get_string 15,reply 

display crlf 

parse reply [2] , fcbl 



rename 



fcb 



;see 
;see 
;see 
;see 
;see 
;see 
;see 
16] 
;see 
;THI 



Func 
Func 
Func 
Func 
Func 
Func 
Func 



tion 
tion 
tion 
tion 
tion 
tion 
tion 



09H 
OAH 
09H 
29H 
09H 
OAH 
09H 



Function 29H 
S FUNCTION 
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Current Disk (Function 19H) 



BX 

CX 



AH 


AL 


BH 


BL 


CM 


CL 


DM 


DL 



FLAGSm I FLAGSi 



Call 

AH = 19H 



Return 

AL 

Currently selected drive 
(0 * A, 1 = B, etc.) 



AL returns the currently selected drive (0 = A:, 1 « B: , 
etc.) . 



Macro Definition: current_disk macro 

mov ah,19H 
int 21H 
endm 

Bxaaple 

The following program displays the currently selected 
(default) drive in a 2-drive system: 

message db "Current disk is $" ;see Function 09H 

;for explanation of $ 
crlf db 13,10,"$" 



func 19H: 



disk_b: 
all done: 



display message 
current_disk 
cmp al,00H 
jne disk_b 
display_char "A" 
jmp all_done 
display_char "B" 
display crlf 



;see Function 09H 
;THIS FUNCTION 
jis it disk A? 
;no, it's disk B: 
;see Function 02H 

;see Function 02H 
;see Function 09H 



SYSTEM CALLS 



Set Disk Transfer Address 



Page 1-70 



Set Disk Transfer Address (Function 1AH) 



Call 

AH = 1AH 
DS:DX 
Disk Transfer Address 



Return 

None 



AH 


AL 


BH 


BL 


CH 


CL 


DH 


OL 



FLAGS" | TLAGSi 



OS 



DX must contain the offset (from the segment address in DS) 
of the Disk Transfer Address. Disk transfers cannot wrap 
around from the end of the segment to the beginning, nor can 
they overflow into another segment. 



NOTE 

If you do not set the Disk 
Transfer Address, MS-DOS 
defaults to offset 80H in the 
Program Segment Prefix. 



Macro Definition: set dta 



Example 



macro 

mov 

mov 

int 

endm 



buffer 

dx, offset buffer 

ah , 1AH 

21H 



The following program prompts for a letter, converts the 
letter to its alphabetic sequence (A = 1, B = 2, etc.), then 
reads and displays the corresponding record from a file 
named ALPHABET.DAT on the disk in drive B:. The file 
contains 26 records; each record is 28 bytes long: 



record size equ 14 
relative record equ 33 



;offset of Record Size 
; field of FCB 

;offset of Relative Record 
; field of FCB 
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fcb 


db 


2,"ALPHABETDAT" 




db 


25 dup (?) 


buffer 


db 


34 dup(?) ,"$" 


prompt 


db 


"Enter letter: $" 


crlf 


db 


13,10,"$" 


funclAH: 


set_dta buffer 




open 


fcb 




mov 


fcb(record si 


get_char : 


display prompt 




read_ 


kbd and echo 




cmp 


al,0DH 




je 


all done 




sub 


al,41H 




mov 


fcb(relative_ 




display crlf 




read_ 


ran fcb 




displ 


ay buffer 




display crlf 




jmp 


get char 


all done: 


close 


fcb 



;THIS FUNCTION 
;see Function OFH 
ze],28 ;set record size 
;see Function 09H 
;see Function 01H 
;just a CR? 
;yes, go home 
;convert ASCII 
;code to record f 
record) ,al 

;set relative record 
;see Function 09H 
;see Function 21H 
;see Function 09H 
;see Function 09H 
;get another character 
;see Function 10H 
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Random Read (Function 21H) 



AH 


AL 


BH 


BL 


CH 


CL 


OH 


OL 



Call 

AH = 21H 
DS:DX 

Opened FCB 



Return 

AL 

00H = Read completed successfully 

01H = EOF 

02H = DTA too small 

03H = EOF, partial record 



DX must contain the offset (from the segment address in DS) 
of an opened FCB. The Current Block (offset OCH) and 
Current Record (offset 20H) fields are set to agree with the 
Relative Record field (offset 21H) , then the record 
addressed by these fields is loaded at the Disk Transfer 
Address . 

AL returns a code that describes the processing: 

Code Meaning 

Read completed successfully. 

End-of-file; no data in the record. 



Not enough room at the Disk Transfer Address 
to read one record; read canceled. 

3 End-of-file; a partial record was read and 
padded to the record length with zeros. 

Macro Definition: read_ran macro fcb 

mov dx, offset fcb 

mov ah,2lH 

int 21H 
endm 

Example 

The following program prompts for a letter, converts the 
letter to its alphabetic sequence (A = 1, B = 2, etc.), then 
reads and displays the corresponding record 
named - ALPHABET.DAT on the disk in drive 



from a file 
B: . The file 



contains 26 records; each record is 28 bytes long: 
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recordsize equ 14 
relative record equ 33 



;offset of Record Size 
; field of FCB 

;offset of Relative Record 
; field of FCB 



fcb 


db 


2, "ALPHABET DAT" 




db 


25 dup (?) 


buffer 


db 


34 dup(?) ,"$" 


prompt 


db 


"Enter letter: $" 


crlf 


db 


13,10,"$" 


func_2lH: 


set_< 


3ta buffer 




open 


fcb 




mov _ 


fcb [record si 


get_char : 


display prompt 




read 


kbd and echo 




cmp 


al,0DH 




je 


all done 




sub 


al,41H 



mov 



fcb'frelative 



all done: 



display 


crlf 


read_ran 


fcb 


display 


buffer 


display 


crlf 


jmp 


get char 


close 


fcb 



•see Function 1AH 
;see Function OFH 

ze],28 ;set record size 
;see Function 09H 
;see Function 01H 
;just a CR? 
;yes, go home 
.•convert ASCII code 
; to record # 

record] ,al ;set relative 
; record 

;see Function 09H 
;THIS FUNCTION 
;see Function 09H 
;see Function 09H 
;get another char. 
;see Function 10H 
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Random Write (Function 22H) 



BX 
CX 
DX 



AH 


AL 


BH 


BL 


CH 


CI 


OH 


DL 



FLAGS" FLAGSi 



Call 

AH = 22H 
DS:DX 

Opened FCB 



Return 

AL 

00H = Write completed successfully 
01H = Disk full 
02H = DTA too small 



DX must contain the offset from the segment address in DS of 
an opened FCB. The Current Block (offset OCH) and Current 
Record (offset 20H) fields are set to agree with the 
Relative Record field (offset 21H) , then the record 
addressed by these fields is written from the Disk Transfer 
Address. If the record size is smaller than a sector (512 
bytes) , the records are buffered until a sector is ready to 
write. 

AL returns a code that describes the processing: 

Code Meaning 

Write completed successfully. 

1 Disk is full. 

2 Not enough room at the Disk Transfer Address 
to write one record; write canceled. 



Macro Definition: write ran 



Example 



macro 

mov 

mov 

int 

endm 



fcb 

dx, offset fcb 

ah, 22H 

21H 



The following program prompts for a letter, converts the 
letter to its alphabetic sequence (A = 1, B = 2, etc.), then 
reads and displays the corresponding record from a file 
named ALPHABET.DAT on the disk in drive B:. After 
displaying the record, it prompts the user to enter a 
changed record. If the user types a new record, it is 
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written to the file; if the user just presses RETURN, the 
record is not replaced. The file contains 26 records; each 
record is 28 bytes long: 



record_size equ 14 
relative_record equ 33 



;offset of Record Size 
; field of FCB 

;offset of Relative Record 
; field of FCB 



fcb db 2,"ALPHABETDAT" 

db 25 dup (?) 

buffer db 26 dup(?) , 13 , 10 ,"$" 

promptl db "Enter letter: $" . 

prompt2 db "New record (RETURN for no change) : $" 

crlf db 13,10,"$" 

reply db 28 dup (32) 

blanks db 26 dup (32) 



func 22H; 



get char 



set_dta 

open 

mov 

display 

read kbd 

cmp 

je 

sub 



buffer 

fcb 

fcb f record_si 

promptl 

and echo 

al,0~DH 

all done 

al,4~lH 

fcbf relative 



displ 


ay 


crlf 




read 


ran 


fcb 




displ 


ay 


buffer 




displ 


ay 


crlf 




displ 


ay 


prompt2 




get str i 


ng 27, reply 




displ 


ay 


crlf 




cmp 




reply[l] ,0 




je 




get char 




xor 




bx,bx 




mov 




bl, reply [11 




move 


string blanks, buf 


move 


str 


ing reply[2] 


,b 


wr i te 


ran fcb 




jmp 




get char 




all done: close 




fcb 





;see Function 1AH 
;see Function OFH 
ze],32 ;set record size 
;see Function 09H 
;see Function 01H 
;just a CR? 
;yes, go home 
;convert ASCII 
;code to record # 
record! ,al 

set relative record 
see Function 09H 
THIS FUNCTION 
see Function 09H 
see Function 09H 
see Function 09H 
see Function OAH 
see Function 09H 
was anything typed 
besides CR? 
no 

get another char, 
to load a byte 
use reply length as 
counter 
fer,26 ;see chapter end 
uffer,bx ; see chapter end 
;THIS FUNCTION 
;get another character 
;see Function 10H 
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File Size (Function 23H) 



BX 

cx 



AH 


At 


BH 


BL 


CH 


CL 


OH 


DL 



FLAGSh I FLAGSi 



Call 

AH = 23H 
DS:DX 

Unopened FCB 



Return 

AL 

00H = Directory entry found 

FFH (255) = No directory entry found 



DX must contain the offset (from the segment address in DS) 
of an unopened FCB. You must set the Record Size field 
(offset OEH) to the proper value before calling this 
function. The disk directory is searched for the first 
matching entry. 

If a matching directory entry is found, the Relative Record 
field (offset 21H) is set to the number of records in the 
file, calculated from the total file size in the directory 
entry (offset 1CH) and the Record Size field of the FCB 
(offset OEH) . AL returns 00. 

If no matching directory is found, AL returns FFH (255). 



NOTE 



If the value of the Record 
Size field of the FCB (offset 
OEH) doesn't match the actual 
number of characters in a 
record, this function does not 
return the correct file size. 
If the default record size 
(128) is not correct, you must 
set the Record Size field to 
the correct value before using 
this function. 



SYSTEM CALLS 



Macro Definition: file size 



File 


Size 
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macro 


fcb 




mov 


dx, offset fcb 




mov 


ah,23H 




int 


21H 




endm 







Bxanple 

The following program prompts for the name of a file, opens 
the file to fill in the Record Size field of the FCB, issues 
a File Size system call, and displays the file size and 
number of records in hexadecimal: 



fcb 


db 


37 dup (?) 




prompt 


db 


'File name: $" 




msgl 


db 


'Record length: 


",13,10,"$" 


msg2 


db 


'Records: " 


,13,10,"$" 


crlf 


db 


13,10,"$" 




reply 


db 


17 dup(?) 




sixteen 


db 


16 




func_23H: 


display 


prompt 


;see Function 09H 




get_string 17, reply 


;see Function 0AH 




cmp 


replyfl] ,0 


;just a CR? 




jne 


get_length 


;no, keep going 




jmp 


all done 


;yes, go home 


get_length: 


display 


crll 


;see Function 09H 




parse 


reply[2] ,fcb 


;see Function 29H 




open 


fcb 


;see Function 0FH 




file_size fcb 


;THIS FUNCTION 




mov 


si, 33 


;offset to Relative 
; Record field 




mov 


di,9 


; reply in msg_2 


convert it: 


cmp 


fcb [si] ,0 


;digit to convert? 




je 


show_it 


;no, prepare message 




convert 


fcbfsi] , sixteen 


,msg_2 [di] 




inc 


si 


;bump n-o-r index 




inc 


di 


;bump message index 




jmp 


convert it 


;check for a digit 


show_it: 


convert 


fcb[14] , sixteen 


,msg_l [15] 




display 


msg_l 


;see Function 09H 




display 


msg 2 


;see Function 09H 




jmp 


func 23H 


;get a filename 


all done: 


close 


fcb 


;see Function 10H 
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Set Relative Record (Function 24H) 



AH 


AL 


BH 


BL 


CH 


CL 


DM 


DL 



FLAGS" FLAGSi 



Call 

AH = 24H 
DS:DX 

Opened FCB 



Return 

None 



DX must contain the offset (from the segment address in DS) 
of an opened FCB. The Relative Record field (offset 21H) is 
set to the same file address as the Current Block (offset 
OCH) and Current Record (offset 20H) fields. 

Macro Definition: set relative record 



macro 


fcb 


mov 


dx, offset fcb 


mov 


ah,24H 


int 


21H 


endm 





Example 

The following program copies a file using the Random Block 
Read and Random Block Write system calls. It speeds the 
copy by setting the record length equal to the file size and 
the record count to 1, and using a buffer of 32K bytes. It 
positions the file pointer by setting the Current Record 
field (offset 20H) to 1 and using Set Relative Record to 
make the Relative Record field (offset 21H) point to the 
same record as the combination of the Current Block (offset 
OCH) and Current Record (offset 20H) fields: 



current_record equ 32 
file size equ 16 



;offset of Current Record 
; field of FCB 
;offset of File Size 
; field of FCB 



fcb db 

filename db 

promptl db 

prompt2 db 

crlf db 



37 dup (?) 

17 dup(?) 
"File to copy: $" 
"Name of copy: $" 

13,10,"$" 



;see Function 09H for 
jexplanation of $ 
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filelength dw 
buffer db 



32767 dup(?) 



func 24H: set_dta buffer 

display promptl 
getstring 15, filename 

display crlf 

parse filename f 2] , fcb 

open fcb 

mov fcb [cur rent_record 

set_relative_ record fcb 
mov ax, word ptr fcbffi 
mov f ile_length,ax 

ranblockread fcb, 1, ax 

display prompt2 

getstring 15, filename 

display crlf 

parse filename ( 2] , fcb 

create fcb 

mov fcb fcur rent_record 

setrelative record fcb 
mov ax, f ile_length 

ranblock write fcb,l,ax 
close "Feb 



;see Function 


1AH 


;see Function 


09H 


;see Function 


OAH 


;see Function 


09H 


;see Function 


29H 


;see Function 


OFH 


] ,0 ;set Current 


Record 


;f ield 




;THIS FUNCTION 




le_size] ;get fi 


le size 


;save it for 




;ran block write 


;see Function 


27H 


;see Function 


09H 


;see Function 


OAH 


jsee Function 


9H 


;see Function 


29H 


;see Function 


16H 


1,0 ; set Current 


Record 


;f ield 




;THIS FUNCTION 




;get original 


file 


; length 




;see Function 


28H 


;see Function 


10H 
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Set Vector (Function 25H) 



AH 


AL 


BH 


BL 


CM 


CL 


OH 


DL 



FLAGSh FLAGSi 



Call 

AH = 25H 
AL 

Interrupt number 
DS:DX 

Interrupt-^handling routine 



Return 

None 



Function 25H should be used to set a particular interrupt 
vector. The operating system can then manage the interrupts 
on a per-process basis. Note that programs should never set 
interrupt vectors by writing them directly in the low memory 
vector table. 

DX must contain the offset (to the segment address in DS) of 
an inter rupt-handling routine. AL must contain the number 
of the interrupt handled by the routine. The address in the 
vector table for the specified interrupt is set to DS:DX. 



Macro Definition: 



set vector 


macro interrupt, seg addr,off addr 






mov al , interrupt 






push ds 






mov ax, seg addr 






mov ds,ax 






mov dx,off addr 






mov ah,25H 






int 21H 






pop ds 






endm 


Example 






Ids 


dx, 


intvector 


mov 


ah, 


25H 


mov 


al, 


intnumber 


int 


21H 





;There are no errors returned 
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Randoa Block Read (Function 27H) 



ex 
ox 



AH 


AL 


BM 


BL 


CH 


CL 


DM 


Dt 



FLAGSh FLAGSl 



06 



Call 

AH = 27H 
DS:DX 

Opened FCB 

cx 

Number of blocks to read 



Return 

AL 

00H = Read completed successfully 

01H » EOF 

02H = End of segment 

03H = EOF, partial record 
CX 

Number of blocks read 



DX must contain the offset (to the segment address in DS) of 
an opened FCB. CX must contain the number of records to 
read; if it contains 0, the function returns without 
reading any records (no operation) . The specified number of 
records — calculated from the Record Size field (offset 
OEH) — is read starting at the record specified by the 
Relative Record field (offset 21H) . The records are placed 
at the Disk Transfer Address. 

AL returns a code that describes the processing: 



Code 

1 
2 



Meaning 

Read completed successfully. 

End-of-file; no data in the record. 

Not enough room at the Disk Transfer Address 
to read one record; read canceled. 

3 End-of-file; a partial record was read 

and padded to the record length with zeros. 

CX returns the number of records read; the Current Block 

(offset OCH) , Current Record (offset 20H) , and Relative 

Record (offset 21H) fields are set to address the next 
record. 
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Macro Definition: 



ran block read 


macro 


fcb, count , rec_size 




mov 


dx, offset fcb 




mov 


ex, count 




mov 


word ptr fcb[14],rec size 




mov 


ah,27H 




int 


21H 




endm 




Example 







The following program copies a file using the Random Block 
Read system call. It speeds the copy by specifying a record 
count of 1 and a record length equal to the file size, and 
using a buffer of 32K bytes; the file is read as a single 
record (compare to the sample program for Function 28H that 
specifies a record lengt h of 1 and a record count equal to 
the file size) : 



current record 
file size 



equ 32 ;offset of Current Record field 
equ 16 ;offset of File Size field 



fcb db 37 dup (?) 

filename db 17 dup(?) 

prompt 1 db "File to copy: $" 

prompt 2 db "Name of copy: $" 

crlf db 13,10,"$" 

dw ? 

32767 dup(?) 



f ilelength 
buffer db 



;see Function 09H for 
explanation of $ 



func_27H: set_dta buffer 

display promptl 

get_string 15, filename 

display crlf 

parse f ilename f 2] , fcb 

open fcb 

mov fcb[current_recor 

setrelativerecord fcb 

mov ax, word ptr fcb[ 

mov f ile_length,ax 

ran_block_read fcb, 1, ax 

display prompt2 

get_string 15, filename 

display crlf 

parse filename [2] , fcb 

create fcb 

mov febtcurrent recor 



set relative record fcb 



;see Function 1AH 
;see Function 09H 
;see Function OAH 
;see Function 09H 
;see Function 29H 
;see Function OFH 
d] ,0 ;set Current 
;Record field 
;see Function 24H 
f ile_size] 
;get file size 
;save it for 
;ran_block_write 
;THIS FUNCTION 
;see Function 09H 
;see Function OAH 
;see Function 09H 
;see Function 29H 
;see Function 16H 
d] ,0 

;set Current Record 
; field 
;see Function 24H 
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mov ax, file_length ;get original file 

; size 
ran block_write fcb,l,ax ;see Function 28H 
close fcb ;see Function 10H 
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Random Block Write (Function 28H) 



AH 


AL 


8H 


Bl 


CM 


CI 


DH 


OL 



FLAGSh FLAGSi 



Call 

AH = 28H 
DS:DX 

Opened FCB 
CX 

Number of blocks to write 
(0 = set File Size field) 



Return 

AL 

00H = Write completed successfully 

01H = Disk full 

02H = End of segment 
CX 

Number of blocks written 



DX must contain the offset (to the segment address in DS) of 
an opened FCB; CX must contain either the number of records 
to write or 0. The specified number of records (calculated 
from the Record Size field, offset OEH) is written from the 
Disk Transfer Address. The records are written to the file 
starting at the record specified in the Relative Record 
field (offset 21H) of the FCB. If CX is 0, no records are 
written, but the File Size field of the directory entry 
(offset 1CH) is set to the number of records specified by 
the Relative Record field of the FCB (offset 21H); 
allocation units are allocated or released, as required. 

AL returns a code that describes the processing: 



Code 



Meaning 



Write completed successfully. 

1 Disk full. No records written. 

2 Not enough room at the Disk Transfer Address 
to read one record; read canceled. 

CX returns the number of records written; the Current Block 

(offset OCH) , Current Record (offset 20H) , and Relative 

Record (offset 21H) fields are set to address the next 
record. 
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Macro Definition: 

ran_block_wr ite macro fcb, count , rec_size 

mov dx, offset fcb 

mov ex, count 

mov word ptr fcb(14] , rec_size 

mov ah,28H 

int 21H 
endm 

Example 

The following program copies a file using the Random Block 
Read and Random Block Write system calls. It speeds the 
copy by specifying a record count equal to the file size and 
a record length of 1, and using a buffer of 32K bytes; the 
file is copied quickly with one disk access each to read and 
write (compare to the sample program of Function 27H, that 
specifies a record count of 1 and a record length equal to 
file size) : 

cur rent record equ 32 joffset of Current Record field 
file size equ 16 ;offset of File Size field 



fcb db 37 dup (?) 

filename db 17 dup(?) 

promptl db "File to copy: $" ;see Function 09H for 

prompt2 db "Name of copy: $" jexplanation of $ 

crlf db 13,10,"$" 

num_recs dw ? 

buffer db 32767 dup(?) 



func 28H: set_dta buffer ;see Function 1AH 
display promptl ;see Function 09H 
getstring 15, filename ;see Function OAH 
display crlf ;see Function 09H 
parse filename [2] , fcb ;see Function 29H 
open fcb ;see Function OFH 

mov fcb{current_record] ,0 

;set Current Record 

;field 
set_relative_record fcb ;see Function 24H 
mov ax, word ptr fcb ( f ile_size] 

;get file size 
mov num_recs,ax ;save it for 

; ran_block_wr ite 
ran_block_read fcb,num_recs , 1 ;THIS FUNCTION 
display prompt2 ;see Function 09H 

get_string 15, filename ;see Function OAH 
display crlf jsee Function 09H 

parse filename [2] , fcb ;see Function 29H 
create fcb ;see Function 16H 

mov fcb[current_record] ,0 ;set Current 

;Record field 
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set_relative_record fcb ;see Function 24H 
mov ax, file_length ;get size of original 
ran_block_wr ite fcb,num_recs,l ;see Function 28H 
close fcb ~~ ysee Function 10H 
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Parse File Naae (Function 29H) 



AH 


AL 


BH 


BL 


CH 


CL 


DM 


OL 



FLAGS" FLAGSi 



Call 

AH = 29H 
AL 

Controls parsing (see text) 
DS:SI 

String to parse 
ES:DI 

Unopened FCB 

Return 

AL 

00H = No wild-card characters 
01H = Wild-card characters used _ 
FFH (255) = Drive letter invalid 

DS:SI 

First byte past string that was 
parsed 

ES:DI 

Unopened FCB 

SI must contain the offset (to the segment address in DS) of 
a string (command line) to parse; DI must contain the 
offset (to the segment address in ES) of an unopened FCB. 
The string is parsed for a filename of the form 
d: filename. ext; if one is found, a corresponding unopened 
FCB is created at ES:DI. 



Bits 0-3 of AL control the parsing and processing. Bits 4-7 
are ignored: 

Bit Value Meaning 



All parsing stops if a file 
encountered. 

1 Leading separators ace igno 

The drive number in Uhe FCB 
(default drive) if the stri 

contain a drive number. 

1 The drive number in the FCB 
if the string does not cont 
number . 

1 The filename in the FCB is 
the string does not contain 

The filename in the FCB is 
if the string does not cont 

1 The extension in the FCB is 
if the string does not cont 

The extension in the FCB is 
if the string does not cont 



separator — is 

red . 

is set to 
ng does not 

is not changed 
ain a drive 

not changed if 

a filename. 
set to 8 blanks 
ain a filename. 

not changed 
ain an extension. 

set to 3 blanks 
ain an extension, 
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If the filename or extension includes an asterisk (*) , all 
remaining characters in the name or extension are set to 
question mark (?) . 

Filename separators: 

:.; , = + / " [ ] \ < > I space tab 

Filename terminators include all the filename separators 
plus any control character. A filename cannot contain a 
filename terminator; if one is encountered, parsing stops. 

If the string contains a valid filename: 



1. AL returns 1 if the filename or extension contains 
a wild card character (* or ?) ; AL returns if 
neither the filename nor extension contains a wild 
card character. 



2. DS:SI point to the first character following the 
string that was parsed. 

ES:DI point to the first byte of the unopened FCB . 

If the drive letter is invalid, AL returns FFH (255) . If 
the string does not contain a valid filename, ES:DI+1 points 
to a blank (ASCII 32) . 

Macro Definition: parse macro string, fcb 



mov 


si, of f set string 


mov 


di, off set fcb 


push 


es 


push 


ds 


pop 


es 


mov 


al,0FH ybits 0, 


mov 


ah,29H 


int 


21H 


pop 


es 


endm 





Bxanple 

The following program verifies the existence of the file 
named in reply to the prompt: 



fcb 


db 


37 dup (?) 


prompt 


db 


"Filename: $" 


reply 


db 


17 dup(?) 


yes 


db 


"FILE EXISTS", 13, 10,"$" 


no 


db 


"FILE DOES NOT EXIST" , 13 , 10 , "$ 
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func_29H: 


display 




prompt 




;see Function 09H 




get stri 


ng 


15, reply 




;see Function OAH 




parse 




reply[21 , 


fcb 


;THIS FUNCTION 




search f 


irst fcb 




;see Function 11H 




cmp 




al,FFH 




;dir. entry found? 




je 




not there 




;no 




display 




yes 




;see Function 09H 




jmp 




continue 






not_there: 


display 




no 






continue: 


. 
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Get Date (Function 2AH) 



BX 
CX 
DX 



AH 


AL 


BH 


BL 


CH 


CL 


DH 


DL 



FLAGSh [ FLAGSt 



Call 

AH = 2AH 



Return 

CX 

Year (1980 - 2099) 
DH 

Month (1 - 12) 
DL 

Day (1 - 31) 
AL 
Day of week (0=Sun., 6=Sat.) 



This function returns the current date set in the operating 
system as binary numbers in CX and DX: 

CX Year (1980-2099) 

DH Month (1 = January, 2 = February, etc.) 

DL Day (1-31) 

AL Day of week (0 = Sunday, 1 = Monday, etc.) 



Macro Definition: get date 



Example 



macro 

mov ah , 2AH 

int 21H 

endm 



The following program gets the date, increments the day, 
increments the month or year, if necessary, and sets the new 
date: 



month 



db 



31,28,31,30,31,30,31,31,30,31,30,31 



func 2AH: get date 



inc 
xor 
mov 
dec 
cmp 
jle 
mov 
inc 
cmp 



dl 

bx,bx 
bl,dh 
bx 



;see above 

; increment day 

;so BL can be used as index 

;move month to index register 

;month table starts with 



dl, month [bx] ;past end of month? 

month_ok ;no, set the new date 

dl,l ;yes, set day to 1 

dh ;and increment month 

dh,12 ;past end of year? 
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jle month_ok ;no, set the new date 

mov dh,l ;yes, set the month to 1 

inc ex ; increment year 

month ok: set date cx,dh,dl ;THIS FUNCTION 
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Set Date (Function 2BH) 



AH 


AL 


BH 


BL 


CH 


CL 


OH 


Ot 



FLAGS* FLAGSi. 



Call 

AH = 2BH 
CX 

Year (1980 - 2099) 
DH 

Month (1 - 12) 
DL 

Day (1 - 31) 

Return 

AL 

00H = Date was valid 

FFH (255) = Date was invalid 



Registers CX and DX must contain a valid date in binary: 

CX Year (1980-2099) 

DH Month (1 = January, 2 = February, etc.) 

DL Day (1-31) 

If the date is valid, the date is set and AL returns 0. If 
the date is not valid, the function is canceled and AL 
returns FFH (255) . 

Macro Definition: set_date macro year , month , day 

mov ex, year 

mov dh, month 

mov dl,day 

mov ah,2BH 

int. 21H 
endm 

Example 

The following program gets the date, increments the day, 
increments the month or year, if necessary, and sets the new 
date: 



month 



db 



31,28,31,30,31,30,31,31,30,31,30,31 



func 2BH: get_date ;see Function 2AH 

inc dl ; increment day 

xor bx,bx ;so BL can be used as index 

mov bl,dh ;move month to index register 

dec bx ;month table starts with 

emp dl, month [bx] jpast end of month? 

jle month ok ;no, set the new date 
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mov 
inc 
cmp 
jle 
mov 
inc 



dl,l 

dh 

dh, 12 

month_ok 

dh, 1 

ex 



month ok: set date cx,dh,dl 



;yes, set day to 1 
;and increment month 
;past end of year? 
;no, set the new date 
;yes, set the month to 1 
; increment year 
;THIS FUNCTION 
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Get Time (Function 2CH) 



BX 

CX 
DX 



AH 


AL 


BH 


BL 


CH 


CL 


OH 


DL 



FLAGS" FLAGSi 



Call 

AH = 2CH 



Return 

CH 

Hour (0 - 23) 
CL 

Minutes (0 - 59) 
DH 

Seconds (0 - 59) 
DL 

Hundredths (0 - 99) 



This function returns the current time set in the operating 
system as binary numbers in CX and DX: 

CH Hour (0-23) 

CL Minutes (0-59) 

DH Seconds (0-59) 

DL Hundredths of a second (0-99) 

Macro Definition: get_time macro 

mov ah , 2CH 
int 21H 
endm 



Exanple 

The following program continuously displays the time until 
any key is pressed: 

"00:00:00. 00", 13, 10,"$" 
10 



time 


db 


ten 


db 


func 2CH: 


ge 



get_time 
convert ch, ten, time 
convert cl,ten, time [3] 
convert dh, ten, time [6] 
convert dl , ten, time [9] 
display time 
check_kbd_status 
cmp al,FFH 
je all_done 
jmp func 2CH 



THIS FUNCTION 

see end of chapter 

see end of chapter 

see end of chapter 

see end of chapter 

see Function 09H 

see Function 0BH 

has a key been pressed? 

yes, terminate 

no, display time 
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Set Time (Function 2DH) 



BX 
CX 
OX 



AH 


AL 


BH 


BL 


CM 


CL 


DM 


OC 



Call 

AH = 2DH 
CH 

Hour (0 - 23) 
CL 

Minutes (0 - 59) 
DH 

Seconds (0 - 59) 
DL 

Hundredths (0 - 99) 



Return 

AL 

00H = Time was valid 

FFH (255) = Time was invalid 



Registers CX and DX must contain a valid time in binary: 

CH Houi \C-23) 

CL Minutes (0-59) 

DH Seconds (0-59) 

DL Hundredths of a second (0-99) 

If the time is valid, the time is set and AL returns 0. If 
the time is not valid, the function is canceled and AL 
returns FFH (255) . 

Macro Definition: 



set time 


macro 


hour , minutes , seconds , hundredths 




mov 


ch,hour 




mov 


cl, minutes 




mov 


dh ,seconds 




mov 


dl , hundredths 




mov 


ah,2DH 




int 


21H 




endm 




Example 







The following program sets the system clock to and 
continuously displays the time. When a character is typed, 
the display freezes; when another character is typed, the 
clock is reset to and the display starts again: 



time 
ten 



db "00:00:00. 00", 13, 10,"$' 
db 10 



func_2DH: 
read_clock : 



settime 0,0,0,0 
get time 



;THIS FUNCTION 
;see Function 2CH 
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stop: 



convert ch, ten, time 

convert cl,ten, time [3] 

convert dh, ten, time [6] 

convert dl , ten, time [9] 

display time 

dir_console_io FFH 

cmp al,00H 

jne stop 

jmp read_clock 

read_kbd 

jmp func 2DH 



see end of chapter 
see end of chapter 
see end of chapter 
see end of chapter 
see Function 09H 
see Function 06H 
was a char . typed? 
yes, stop the timer 
no keep timer on 
see Function 08H 
keep displaying time 
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Set/Reset Verify Flag (Function 2EH) 



BX 
CX 
DX 



AH 


AL 


BH 


BL 


CH 


CL 


OH 


OL 



FLAGSh FLAGSi 



Call 

AH » 2EH 
AL 

00H = Do not verify 

01H = Verify 



Return 

None 



AL must be either 1 (verify after each disk write) or 
(write without verifying). MS-DOS checks this flag each 
time it writes to a disk. 

The flag is normally off; you may wish to turn it on when 
writing critical data to disk. Because disk errors are rare 
and verification slows writing, you will probably want to 
leave it off at other times. 



Macro Definition: verify 



macro 


switch 


mov 


al, switch 


mov 


ah,2EH 


int 


21H 


endm 





Example 

The following program copies the contents of a single-sided 
disk in drive A: to the disk in drive B: f verifying each 
write. It uses a buffer of 32K bytes: 



on 
off 



equ 
equ 



prompt 

start 
buffer 



db "Source in A, target in B",13,10 

db "Any key to start. $" 

dw 

db 64 dup (512 dup(?)) ; 64 sectors 



func 2DHi 



display prompt 
read kbd 
veriTy on 



;see Function 09H 
;see Function 08H 
;THIS FUNCTION 
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mov ex, 5 ;copy 64 sectors 

;5 times 
copy: push ex ;save counter 

abs_disk_read 0, buffer ,64 , start 

;see Interrupt 25H 
abs_disk_write 1, buffer, 64, start 

;see Interrupt 26H 
add start, 64 ;do next 64 sectors 

pop ex ; restore counter 

loop copy ;do it again 

verify off ;THIS FUNCTION 

disk_ read 0, buffer ,64, start ;see Interrupt 25H 

abs_disk_write 1, buffer ,64, start 

;see Interrupt 26H 
add start, 64 ;do next 64 sectors 

pop ex ; restore counter 

loop copy ;do it again 

verify off 
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Call 

AH = 2FH 
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AX 


AH 


At 


BX 


BH 


BL 


CX 


CH 


CL 


OX 


OH 


01 



FLAGSm fLAGSl 



Return 
ES:BX 

Points to Disk Transfer Address 



Function 2FH returns the DMA transfer address. 

Error returns: 
None. 



Bxanple 

mov 
int 



ah , 2FH 

21H 

;es:bx has current DMA transfer address 
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Get DOS Version Number (Function 30H) 



BX 

ex 

DX 



AH 


At. 


BH 


BL 


CH 


CL 


DH 


Dl 



FLAGSm I FLAGSi 



Call 

AH = 30H 



Return 

AL 

Major version number 
AH 

Minor version number 



This function returns the MS-DOS version number. On return, 
AL.AH will be the two-part version designation; i.e., for 
MS-DOS 1.28, AL would be 1 and AH would be 28. For 
pre-1.28, DOS AL = . Note that version 1.1 is the same as 
1.10, not the same as 1.01. 

Error returns: 
None. 



Example 

mov 
int 



ah,30H 

21H 

al is the major version number 

ah is the minor version number 

bh is the OEM number 

bl:cx is the (24 bit) user number 
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Keep Process (Function 31H) 

Call 



BX 
CX 
DX 



AH 


AL 


BM 


BL 


CH 


CI 


OH 


tx 



FLAGSh I FLAGSi 



AH 

AL 

1 

DX 



31H 



Exit code 



Memory size, in paragraphs 

Return 

None 



This call terminates the current process and attempts to set 
the initial allocation block to a specific size in 
paragraphs. It will not free up any other allocation blocks 
belonging to that process. The exit code passed in AX is 
retrievable by the parent via Function 4DH. 



This method is preferred over Interrupt 27H and 
advantage of allowing more than 64K to be kept. 

Error returns: 
None . 



has the 



Exanple 



mov 
mov 
mov 
int 



al , exitcode 
dx, parasize 
ah, 31H 
21H 
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COWTROL-C Check (Function 33H) 



AX 
BX 
CX 
DX 



AH 


At 


BH 


BL 


CH 


CI 


DH 


«. 



FLAGSh I FLAGS! 



Call 

AH = 33H 
AL 

Function 

00H = Request current state 

01H = Set state 
DL (if setting) 

00H = Off 

01H = On 



Return 

DL 

00H ■ Off 
01H = On 



MS-DOS ordinarily checks for a CONTROL-C on the controlling 
device only when doing function call operations 01H-0CH to 
that device. Function 33H allows the user to expand this 
checking to include any system call. For example, with the 
CONTROL-C trapping off, all disk I/O will proceed without 
interruption; with CONTROL-C trapping on, the CONTROL-C 
interrupt is given at the system call that initiates the 
disk operation. 



NOTE 

Programs that wish to use 
calls 06H or 07H to read 
CONTROL-Cs as data must ensure 
that the CONTROL-C check is 
off. 



Error return: 
AL = FF 

The function passed in AL was not in the range 

0:1. 



Exaaple 



mov 
mov 
mov 



dl,val 
ah,33H 
al,func 
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int 21H 

; If al was 0, then dl has the current value 
;of the CONTROL-C check 



SYSTEM CALLS 



Get Interrupt Vector Page 1-104 



Get Interrupt Vector (Function 35H) 



Call 

AK = 3 5H 
AL 

Interrupt number 



AH 


AL 


BH 


6L 


CH 


CL 


DH 


Dl 



FLAGS" | FLAGSi 



Return 

ES:BX 

Pointer to interrupt routine 



This function returns the interrupt vector associated with 
an interrupt. Note that programs should never get an 
interrupt vector by reading the low memory vector 1 table 
directly. 

Error returns: 
None. 



Example 



mov 
mov 
int 



ah,35H 

al, interrupt 
21H 
es:bx now has long pointer to interrupt routine 
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Get Disk Free Space (Function 36H) 



ex 
ox 



AH 


AL 


BH 


BL 


CH 


CI 


OH 


Dl 



FLAGSh I FLAGSi 



Call 

AH = 36H 
DL 

Drive ( = Default, 

1 = A, etc.) 



Return 

BX 

Available clusters 
DX 

Clusters per drive 
CX 

Bytes per sector 
AX 

FFFF if drive number is invalid; 
otherwise sectors per cluster 

This function returns free space on disk along with 
additional information about the disk. 

Error returns: 
AX = FFFF 

The drive number given in DL was invalid. 



Example 



mov 
mov 
int 



;0 = default, A = 1 



ah,36H 

dl, Drive 

21H 
bx = Number of free allocation units on drive 
dx = Total number of allocation units on drive 
ex = Bytes per sector 
ax = Sectors per allocation unit 
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Return Country-Dependent Information (Function 38H) 



BX 
CX 
DX 



AH 


At 


BH 


Bl 


CH 


CL 


DM 


DL 



FLAGSh FLAGSl 



Call 

AH = 38H 
DS:DX 

Pointer to 32-byte memory area 
AL 

Function code. In MS-DOS 2.0, 

must be 



Return 

Carry set: 
AX 

2 = file not found 
Carry not set: 

DX:DS filled in with country data 



The value passed in AL is either (for current country) or 

a country code. Country codes are typically the 
international telephone prefix code for the country. 

If DX - -1, then the call sets the current country (as 

returned by the AL=0 call) to the country code in AL. If 

the country code is not found, the current country is not 
changed. 



NOTE 

Applications must assume 32 
bytes of information. This 
means the buffer pointed to by 
DS:DX must be able to 
accommodate 32 bytes. 



This function is fully supported only in versions of MS-DOS 
2.01 and higher. It exists in MS-DOS 2.0, but is not fully 
implemented. 

This function returns, in the block of memory pointed to by 
DS:DX, the following information pertinent to international 
applications: 
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WORD Date/time format 



5 BYTE ASCIZ string 
currency symbol 



2 BYTE ASCIZ string 
thousands, separator 



2 BYTE ASCIZ string 
decimal separator 



2 BYTE ASCIZ string 
date separator 



2 BYTE ASCIZ string 
time separator 



1 BYTE Bit field 



1 BYTE 
Currency places 



1 BYTE 
time format 



DWORD 

Case Mapping call 



2 BYTE ASCIZ string 
data list separator 



The format of most of these entries is ASCIZ (a NUL 
terminated ASCII string), but a fixed size is allocated for 
each field for easy indexing into the table. 

The date/time format has the following values: 

- USA standard h:m:s m/d/y 

1 - Europe standard h:m:s d/m/y 

2 - Japan standard y/m/d h:m:s 

The bit field contains 8 bit values. Any bit not currently 
defined must be assumed to have a random value. 

Bit = If currency symbol precedes the 
currency amount. 
= 1 If currency symbol comes after 
the currency amount. 
Bit 1 = If the currency symbol immediately 
precedes the currency amount. 
= 1 If there is a space between the 
currency symbol and the amount. 
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The time format has the following values: 

0-12 hour time 
1-24 hour time 

The currency places field indicates the number of places 
which appear after the, decimal point on currency amounts. 

The Case Mapping call is a FAR procedure which will perform 
country specific lower-to-uppercase mapping on character 
values from 80H to FFH. It is called with the character to 
be mapped in AL. It returns the correct upper case code for 
that character, if any, in AL . AL and the FLAGS are the 
only registers altered. It is allowable to pass this 
routine code below 80H; however nothing is done to 
characters in this range. In the case where there is no 
mapping, AL is not altered. 

Error returns: 
AX 
2 = file not found 

The country passed in AL was not found (no 



table for specified country) . 



Example 



Ids 


dx , 


blk 


mov 


ah, 


38H 


mov 


al, 


Country code 


int 


21H 





;AX = Country code of country returned 
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Create Sub-Directory (Function 39H) 



AH 


AL 


BH 


BL 


CH 


CI 


DH 


DL 



FLAGSh FLAOSl 



Call 

AH = 39H 
DX:DS 

Pointer to pathname 



Return 

Carry set: 

AX 

3 = path not found 
5 = access denied 

Carry not set: 
No error 



Given a pointer to an ASCIZ name, this function creates a 
new directory entry at the end. 

Error returns: 
AX 
3 = path not found 

The path specified was invalid or not found. 
5 = access denied 

The directory could not be created (no room in 
parent directory) , the directory/file already 
existed or a device name was specified. 



Example 

Ids 
mov 
int 



dx, name 
ah, 39H 
21H 



SYSTEM CALLS 



Remove Directory Entry 



Page 1-110 



Remove a Directory Entry (Function 3AH) 



AH 


At 


OH 


BL 


CM 


CL 


DH 


Dt 



FLAGSh FlAQSt 



Call 

AH = 3AH 
DS:DX 

Pointer to pathname 



Return 

Carry set: 

AX 

3 = path not found 

5 = access denied 

16 = current directory 

Carry not set: 
No error 



Function 3AH is given an ASCIZ name of a directory. That 
directory is removed from its parent directory. 

Error returns: 
AX 
3 = path not found 

The path specified was invalid or not found. 
5 = access denied 

The path specified was not empty, not a 

directory, the root directory, or contained 

invalid information. 
16 = current directory 

The path specified was the current directory 

on a drive. 



Example 



Ids 


dx , name 


mov 


ah , 3AH 


int 


21H 
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Change the Current Directory (Function 3BH) 



ax 
ex 



AH 


AL 


BH 


BL 


CH 


CL 


OH 


DL 



FUAGSm FLAOSi 



Call 

AH = 3BH 
DS:DX 

Pointer to pathname 



Return 

Carry set: 
AX 

3 = path not found 
Carry not set: 

No error 



Function 3BH is given the ASCIZ name of the directory which 
is to become the current directory. If any member of the 
specified pathname does not exist, then the current 
directory is unchanged. Otherwise, the current directory is 
set to the string. 

Error returns: 
AX 
3 = path not found 

The path specified in DS:DX either indicated a 
file or the path was invalid. 



Example 



Ids 


dx, name 


mov 


ah, 3BH 


int 


21H 
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Create a Pile (Function 3CH) 



AH 


— — — 


BH 


BL 


CH 


CL 


DM 


OL 



FLAGSm FLAOSl 



Call 

AH = 3CH 
DS:DX 

Pointer to pathname 
CX 

File attribute 



Return 

Carry set: 
AX 

5 = access denied 

3 = path not found 

4 = too many open files 
Carry not set: 

AX is handle number 



Function 3CH creates a new file or truncates an old file to 
zero length in preparation for writing. If the file did not 
exist, then the file is created in the appropriate directory 
and the file is given the attribute found in CX. The file 
handle returned has been opened for read/write access. 

Error returns: 
AX 

5 = access denied 

The attributes specified in CX contained one 
that could not be created (directory, volume 
ID) , a file already existed with a more 
inclusive set of attributes, or a directory 
existed with the same name. 

3' = path not found 

The path specified was invalid. 

4 = too many open files 

The file was created with the specified 
attributes, but there were no free handles 
available for the process, or the internal 
system tables were full. 



Example 



Ids 


dx, name 


mov 


ah , 3CH 


mov 


ex, attribute 


int 


21H 



ax now has the handle 
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Open a File (Function 3DH) 



BX 
CX 



AH 


AL 


BH 


BL 


CM 


CL 


OH 


DL 



Call 

AH = 3DH 
AL 

Access 

= File opened for reading 

1 =» File opened for writing 

2 = File opened for both 
reading and writing 



Return 

Carry set: 

AX 

12 = invalid access 

2 = file not found 

5 = access denied 

4 = too many open files 

Carry not set: 

AX is handle number 



Function 3DH associates a 16-bit file handle with a file 



The following values are allowed: 
ACCESS Function 



file is opened for reading 

1 file is opened for writing 

2 file is opened for both reading and writing. 

DS:DX point to an ASCIZ name of the file to be opened. 

The read/write pointer is set at the first byte of the file 
and the record size of the file is 1 byte. The returned 
file handle must be used for subsequent I/O to the file. 
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Error returns: 

AX 

12 = invalid access 

The access specified in AL was not in the 

range 0:2. 
2 = file not found 

The path specified was invalid or not found. 
5 = access denied 

The user attempted to open a directory or 

volume-id, or open a read-only file for 

writing. 
4 = too many open files 

There were no free handles available in the 

current process or the internal system tables 

were full. 



Example 



Ids dx, name 
mov ah, 3DH 
mov al, access 
int. 21H 

; ax has error or file handle 

; If successful open 
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Close a Pile Handle (Function 3EH) 



AX 
BX 
CX 
OX 



AH 


AL 


8M 


BL 


CH 


CL 


DM 


DL 



FLAGSm I FLAOSi 



Call 

AH = 3EH 
BX 

File handle 



Return 

Carry set: 
AX 

6 = invalid handle 
Carry not set: 

No error 



In BX is passed a file handle (like that returned by 
Functions 3DH, 3CH, or 45H) , Function 3EH closes the 
associated file. Internal buffers are flushed. 

Error return: 
AX 
6 = invalid handle 

The handle passed in BX was not currently 

open. 



Example 



mov 


bx, handle 


mov 


ah, 3EH 


int 


21H 
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Read From File/Device (Function 3FH) 

Call 



BX 
CX 



AH 


At 


BH 


BL 


CH 


CL 


OH 


OL 



AH = 3FH 
DS:DX 

Pointer to buffer 
CX 

Bytes to read 

BX 

File handle 



| FtAGSi 



Return 

Carry set: 
AX 

Number of bytes read 

6 = invalid handle 

5 = error set: 
Carry not set: 

AX = number of bytes read 

Function 3FH transfers count bytes from a file into a buffer 
location. It is not guaranteed that all count bytes will be 
read; for example, reading from the keyboard will read at 
most one line of text. If the returned value is zero, then 
the program has tried to read from the end of file. 



All I/O is done using normalized pointers; 
wraparound will occur. 



no segment 



Error returns: 
AX 
6 = invalid handle 

The handle passed in BX was not currently 
open. 
5 = access denied 

The handle passed in BX was opened in a mode 
that did not allow reading. 



Example 

Ids 
mov 
mov 
mov 
int 



dx, buf 
ex, count 
bx, handle 
ah, 3FH 
21H 
ax has number of bytes read 
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Write to a File or Device (Function 40B) 

Call 

Bx I bh I a. I AH = 40H 

ex I ch I cl I DS:DX 

Pointer to buffer 
CX 

Bytes to write 
BX 

File handle 



AH 


AL 


BH 


BL 


CH 


CL 


OH 


OL 



FLAGS" I flAOSt. 



Return 
Carry set: 
AX 

Number of bytes written 

6 = invalid handle 

5 = access denied 
Carry not set: 
AX = number of bytes written 

Function 40H transfers count bytes from a buffer into a 
file. It should be regarded as an error if the number of 
bytes written is not the same as the number requested. 

The write system call with a count of zero (CX = 0) will set 
the file size to the current position. Allocation units are 
allocated or released as required. 

All I/O is done using normalized pointers; no segment 
wraparound will occur. 

Error returns: 
AX 
6 = invalid handle 

The handle passed in BX was not currently 
open . 
5 = access denied 

The handle was not opened in a mode that 
allowed writing. 



Example 

Ids 
mov 
mov 
mov 
int 



dx, buf 
ex, count 
bx, handle 
ah, 40H 
21H 
; ax has number of bytes written 
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Delete a Directory Entry (Function 41B) 







BH 


BL 


CH 


CL 


&ilr' 


' V; 




SP 


BP 


SI 


a 




ip 


flagsh 1 . fUtifc 




cs 


?.;■;. -*i o.- : --:..' 


ss 


ES 



Call 

AH « 41H 
DS:DX 

Pointer to path name 



Return 

Carry set: 

AX 

2 « file not found 
5 = access denied 

Carry not set: 
No error 



Function 41H removes a directory entry associated with a 
filename. 

Error returns: 
AX 
2 « file not found 

The path specified was invalid or not found. 
5 - access denied 

The path specified was a directory or 
read-only. 



Bxaaple 



Ids 


dx, name 


mov 


ah, 41H 


int 


21H 
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Move File Pointer (Function 42H) 

Call 

AH = 4 2H 
CX:DX 

Distance to move, in bytes 
AL 

Method of moving: 

(see text) 
BX 

File handle 



AH 


AL 


8H 


BL 


CH 


CL 


OH 


DL 



FLAGSm I FLAGSl 



Return 

Carry set: 
AX 

6 = invalid handle 

1 = invalid function 
Carry not set: 

DX:AX = new pointer location 

Function 42H moves the read/write pointer according to one 
of the following methods: 

Method Function 



The pointer is moved to offset bytes from the 
beginning of the file. 

1 The pointer is moved to the current location 
plus offset. 

2 The pointer is moved to the end of file plus 
offset. 

Offset should be regarded as a 32-bit integer with CX 
occupying the most significant 16 bits. 

Error returns: 
AX 
6 = invalid handle 

The handle passed in BX was not currently 
open. 
1 = invalid function 

The function passed in AL was not in the range 
0:2. 



Example 



mov 
mov 
mov 
mov 
mov 
int 



dx, offsetlow 

ex, offsethigh 

al, method 

bx, handle 

ah, 42H 
21H 
; dx:ax has the new location of the pointer 
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Change Attributes (Function 43H) 



BX 

CX 
DX 



AM 


AL 


BH 


BL 


CH 


CI 


DH 


DL 



FLAGSm I FLAQSt 



Call 

AH = 4 3H 
DS:DX 

Pointer to path name 
CX (if AL = 01) 

Attribute to be set 
AL 

Function 

01 Set to CX 

00 Return in CX 



Return 

Carry set: 
AX 

3 = path not found 

5 = access denied 

1 = invalid function 
Carry not set: 

CX attributes (if AL = 00) 

Given an ASCIZ name, Function 42H will set/get the 
attributes of the file to those given in CX. 

A function code is passed in AL: 

AL Function 

Return the attributes of the file in CX. 

1 Set the attributes of the file to those in CX. 

Error returns: 
AX 
3 = path not found 

The path specified was invalid. 
5 = access denied 

The attributes specified in CX contained one 

that could not be changed (directory, volume 

ID). 
1 = invalid function 

The function passed in AL was not in the range 

0:1. 



Example 






Ids 


dx, 


name 


mov 


ex, 


attribute 


mov 


al, 


func 


int 


ah, 


43H 


int 


21H 
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I/O Control for Devices (Function 44H) 



AH 


AL 


BM 


BL 


CH 


Ct 


DM 


CM. 



FLAGSh flaqsl 



Call 

Bx I w \ «• I AH = 44H 

ex ch ct BX 

ox I dm I Dt I Handle 
BL 

Drive (for calls AL = 4 , 5 

= default, 1 = A, etc.) 
DS:DX 

Data or buffer 
CX 

Bytes to read or write 
AL 

Function code; see text 

Return 

Carry set: 
AX 

6 = invalid handle 

1 = invalid function 
13 = invalid data 

5 = access denied 
Carry not set: 
AL = 2,3,4,5 
AX = Count transferred 
AL = 6,7 

00 = Not ready 

FF = Ready 

Function 44H sets or gets device information associated with 
an open handle, or sends/receives a control string to a 
device handle or device. 

The following values are allowed for function: 

Request Function 



Get device information (returned in DX) 

Set device information (as determined by DX) 

Read CX number of bytes into DS:DX from device 

control channel 

Write CX number of bytes from DS:DX to device 

control channel 



Same as 2 only 
0=default,A:=l,B:=2, . 
Same as 3 only 
0=default,A:=l,B:=2, , 
Get input status 
Get output status 



drive 
drive 



number 
number 



in BL 
in BL 



This function can be used to get information about device 
channels. Calls can be «>.&de on regular files, but only 
calls 0,6 and 7 are defined is> that case (AL=0,6,7). All 
other calls return an invalid function error. 
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Calls AL=0 and AL=1 

The bits of DX are defined as follows for calls 
AL=0 and AL=1. Note that the upper byte MUST be zero 
on a set call. 



15 


14 


13 12 11 10 9 8 


7 


6 


5 


4 


3 


2 


1 





R 


C 




I 


E 


R 


S 


I 


I 


I 


I 


e 


T 




S 





A 


P 


S 


S 


S 


S 


s 


R 


Reserved 


D 


F 


W 


E 


C 


N 


C 


C 




L 




E 






C 


L 


U 





I 








V 






L 


K 


L 


T 


N 

























ISDEV = 1 if this channel is a device 

= if this channel is a disk file (Bits 8-15 
= in this case) 

If ISDEV = 1 

EOF = if End Of File on input 

RAW = 1 if this device is in Raw mode 

= if this device is cooked 

ISCLK = 1 if this device is the clock device 

ISNUL = 1 if this device is the null device 

ISCOT = 1 if this device is the console output 

ISCIN = 1 if this device is the console input 

SPECL = 1 if this device is special 

CTRL = if this device can not do control 
strings via calls AL=2 and AL=3. 

CTRL =1 if this device can process 
control strings via calls AL=2 and 
AL=3. 

NOTE that this bit cannot be set. 



If ISDEV = 

EOF = if channel has been written 
Bits 0-5 are the block device number for 
the channel (0 = A: , 1 = B: , ...) 

Bits 15,8-13,4 are reserved and should not be 
altered. 

Calls 2. .5: 

These four calls allow arbitrary control strings to be 
sent or received from a device. The call syntax is 
the same as the read and write calls, except for 4 and 
5, which take a drive number in BL instead of a handle 
in BX. 
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An invalid function error is returned if the 
CTRL bit (see above) is 0. 

An access denied is returned by calls AL=4,5 if 
the drive number is invalid. 

Calls 6,7: 

These two calls allow the user to check if a file 
handle is ready for input or output. Status of 
handles open to a device is the intended use of these 
calls, but status of a handle open to a disk file is 
allowed, and is defined as follows: 

Input: 

Always ready (AL=FF) until EOF reached, then 

always not ready (AL=0) unless current 

position changed via LSEEK. 
Output: 

Always ready (even if disk full) . 



IMPORTANT 

The status is defined at the 
time the system is CALLED. On 
future versions, by the time 
control is returned to the 
user from the system, the 
status returned may NOT 
correctly reflect the true 
current state of the device or 
file. 



Error returns: 
AX 
6 = invalid handle 

The handle passed in BX was not currently 
open. 
1 = invalid function 

The function passed in AL was not in the range 
0:7. 
13 = invalid data 
5 = access denied (calls AL=4..7) 
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Example 








mov 


bx, 


Handle 


(or 


mov 


bl. 


drive 




mov 


dx, 


Data 


(or 


Ids 


dx. 


buf 




mov 


ex, 


count 




mov 


ah, 


44H 




mov 


al, 


f unc 




int 


21H 





for calls AL=4,5 
0=default,A:=l. ..) 

and 

for calls AL=2,3,4,5) 



For calls AL=2,3,4,5 AX is the number of bytes 
transferred (same as READ and WRITE) . 
For calls AL=6,7 AL is status returned, AL=0 if 
status is not ready, AL=0FFH otherwise. 
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Duplicate a File Handle (Function 45H) 



Call 

AH = 4 5H 
BX 

File handle 



AH 


Al 


BM 


BL 


CH 


CI 


OH 


RL 



TLAGSh FLAG&. 



Return 

Carry set: 

AX 

6 = invalid handle 

4 = too many open files 

Carry not set: 

AX = new file handle 



Function 45H takes an already opened file handle and returns 
a new handle that refers to the same file at the same 
position. 

Error returns: 
AX 
6 = invalid handle 

The handle passed in BX was not currently 
open. 
4 = too many open files 

There were no free handles available in the 
current process or the internal system tables 
were full. 



Bxanple 



mov 
mov 
int 



bx, fh 
ah, 45H 
21H 
ax has the returned handle 
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Force a Duplicate of a Handle (Function 46H) 



AH 


AL 


BH 


BL 


CH 


CI 


DH 


PI. 



Call 

AH = 46H 
BX 

Existing file handle 
CX 

New file handle 



Return 

Carry set: 

AX 

6 = invalid handle 

4 = too many open files 

Carry not set: 
No error 



Function 46H takes an already opened file handle and returns 
a new handle that refers to the same file at the same 
position. If there was already a file open on handle CX, it 
is closed first. 

Error returns: 
AX 
6 = invalid handle 

The handle passed in BX was not currently 
open . 
4 = too many open files 

There were no free handles available in the 
current process or the internal system tables 
were full. 



Example 



mov 


bx, fh 


mov 


ex, newfh 


mov 


ah, 46H 


int 


21H 
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AH 


AL 


BM 


01 


C.H 


CL 


OH 


DC 



Return Text of Current Directory (Function 47H) 



Call 

AH = 4 7H 
DS:SI 

Pointer ho 64-byte memory area 
DL 

Drive number 



Return 
Carry set: 
AX 

15 = invalid drive 
Carry not set: 

No error 



FLAGS" FLAOSl 



Function 47H returns the current directory for a particular 

drive. The directory is root-relative and does not contain 

the drive specifier or leading path separator. The drive 
code passed in DL is 0=default, 1=A:, 2=B:, etc. 

Error returns: 

AX 

15 = invalid drive 

The drive specified in DL was invalid. 



Example 



mov ah, 47H 

Ids si, area 

mov dl, drive 

int 21H 

; ds:si is a pointer to 64 byte area that 
; contains drive current directory. 
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Allocate Memory (Function 48H) 



AH 


At. 


BH 


BC 


CH 


CL 


DH 


DL 



FLAGSh FLAOSl 



Call 

AH = 48H 
BX 

Size of memory to be allocated 



Return 
Carry set: 
AX 

8 = not enough memory 

7 = arena trashed 
BX 

Maximum size that could be allocated 
Carry not set: 
AX:0 

Pointer to the allocated memory 



Function 48H returns a pointer to a free block of memory 
that has the requested size in paragraphs. 

Error return: 

AX 
8 = not enough memory 

The largest available free block is smaller 
than that requested or there is no free block. 
7 = arena trashed 

The internal consistency of the memory arena 
has been destroyed. This is due to a user 
program changing memory that does not belong 
to it. 



Example 



mov 
mov 
int 



bx,size 

ah,48H 

21H 
; ax:0 is pointer to allocated memory 
; if alloc fails, bx is the largest block available 
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Free Allocated Memory (Function 49H) 



AH 


AL 


BH 


BL 


CM 


CL 


DH 


OL 



Call 

AH = 49H 

ES 

Segment address of memory 

area to be freed 



Return 

Carry set: 

AX 

9 = invalid block 
7 = arena trashed 

Carry not set: 
No error 



Function 49H returns a piece of memory to the system pool 
that was allocated by Function Request 49H. 

Error return: 

AX 
9 = invalid block 

The block passed in ES is not one allocated 
via Function Request 49H. 
7 = arena trashed 

The internal consistency of the memory arena 
has been destroyed. This is due to a user 
program changing memory that does not 'belong 
to it. 



Example 




mov 


es , block 


mov 


ah,49H 


int 


21H 
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Modify Allocated Memory Blocks (Function 4AH) 



AH 


AL 


BH 


BL 


CH 


CL 


DH 


DL 



Call 

AH = 4AH 
ES 

Segment address of memory area 
BX 

Requested memory area size 



FLAGSh FLAOSl 



Return 

Carry set: 
AX 

9 = invalid block 

7 = arena trashed 

8 = not enough memory 
BX 

Maximum size possible 
Carry not set: 
No error 

Function 4AH will attempt to grow/shrink an allocated block 
of memory. 

Error return: 
AX 
9 = invalid block 

The block passed in ES is not one allocated 
via this function. 

7 = arena trashed 

The internal consistency of the memory arena 
has been destroyed. This is due to a user 
program changing memory that does not belong 
to it. 

8 = not enough memory 

There was not enough free memory after the 
specified block to satisfy the grow request. 



Exaaple 



mov 
mov 
mov 
int 



es, block 

bx,newsize 

ah , 4AH 

21H 
; if setblock fails for growing, BX will have the 
; maximum size possible 
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AH 


At 


BH 


BL 


CH 


CI 


OH 


DL 



Load and Execute a Program (Function 4BH) 

Call 

AH = 4BH 
DS:DX 

Pointer to pathname 
ES:BX 

Pointer to parameter block 
AL 

00 = Load and execute program 
03 = Load program 

Return 

Carry set: 
AX 

1 = invalid function 

10 = bad environment 

11 = bad format 

8 = not enough memory 

2 = file not found 
Carry not set: 

No error 

This function allows a program to load another program into 
memory and (default) begin execution of it. DS:DX points to 
the ASCIZ name of the file to be loaded. ES:BX points to a 
parameter block for the load. 

A function code is passed in AL: 

AL Function 

Load and execute the program. A program header is 
established for the program and the terminate and 
CONTROL-C addresses are set to the instruction after 
the EXEC system call. 

3 Load (do not create) the program header, and do 
not begin execution. This is useful in loading 
program overlays. 
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For each value of AL, the block has the following 
format: 

AL = --> load/execute program 



WORD segment address of 
environment . 



DWORD pointer to command 
line at 80H 



DWORD pointer to default 
FCB to be passed at 5CH 



DWORD pointer to default 
FCB to be passed at 6CH 



AL = 3 -> load overlay 



WORD segment address where 
file will be loaded. 



WORD relocation factor to 
be applied to the image. 



Note that all open files of a process are duplicated in the 
child process after an EXEC. This is extremely powerful; 
the parent process has control over the meanings of stdin, 
stdout, stderr, stdaux and stdprn. The parent could, for 
example, write a series of records to a file, open the file 
as standard input, open a listing file as standard output 
and then EXEC a sort program that takes its input from stdin 
and writes to stdout. 

Also inherited (or passed from the parent) is an 
"environment." This is a block of text strings (less than 
32K bytes total) that convey various configuration 
parameters. The format of the environment is as follows: 
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(paragraph boundary) 



BYTE 


ASCIZ string 


1 


BYTE 


ASCIZ string 


2 


... 


BYTE 


ASCIZ string 


n 


BYTE 


of zero 





Typically the environment strings have the form: 

pa rameter= value 

For example, C0MMAND.COM might pass its execution search 
path as: 

PATH=A:\BIN; B:\BASIC\LIB 

A zero value of the environment address causes the child 
process to inherit the parent's environment unchanged. 

Error returns: 
AX 

1 = invalid function 

The function passed in AL was not 0, 1 or 3. 

10 = bad environment 

The environment was larger than 32Kb. 

11 = bad format 

The file pointed to by DS:DX was an EXE format 
file and contained information that was 
internally inconsistent. 
8 = not enough memory 

There was not enough memory for the process to 
be created. 

2 = file not found 

The path specified was invalid or not found. 

Example 



Ids 


dx, 


name 


les 


bx, 


blk 


mov 


ah, 


4BH 


mov 


al, 


f unc 


int 


21H 
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Terminate a Process (Function 4CT3) 



Call 

AH = 4CH 
AL 

Return code 



AH 


AL 


BM 


Bl 


CM 


CL 


DM 


DL 



FLAGSm TLAGSt 



Return 

None 



Function 4CH terminates the current process and transfers 
control to the invoking process. In addition, a return code 
may be sent. All files open at the time are closed. 

This method is preferred over all others (Interrupt 20H, JMP 
0) and has the advantage that CS:0 does not have to point to 
the Program Header Prefix. 

Error returns: 
None . 



Example 



mov 


al , code 


mov 


ah , 4CH 


int 


21H 
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Retrieve the Return Code of a Child (Punction 4DH) 



AH 


AL 


BH 


BL 


CH 


CL 


OH 


OL 



FUAGSm I FlAQSl 



Call 

AH ■ 4DH 



Return 
AX 

Exit code 



Function 4DH returns the Exit code specified 
process. It returns this Exit code only once, 
of this code is that sent by the Exit 
byte is one of the following: 

- Terminate/abort 

1 - CONTROL-C 

2 - Hard error 

3 - Terminate and stay resident 

Error returns: 
None. 



by a child 

The low byte 

routine. The high 



Exaaple 



mov 
int 



ah, 4DH 
21H 
ax has the exit code 
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Find Natch Pile (Function 4EH) 



BX 
CX 
DX 



AH 


* 1 


BH 


» 1 


CM 


a j 


DM 


«- i 



FLAGS* I HMJSL 



Call 

AH = 4EH 
DS:DX 

Pointer to pathname 
CX 

Search attributes 



Return 

Carry set: 

AX 

2 = file not found 
18 = no more files 

Carry not set: 
No error 



Function 4EH takes a pathname with wild-card characters in 
the last component (passed in DS:DX), a set of attributes 
(passed in CX) and attempts to find all files that match the 
pathname and have a subset of the required attributes. A 
datablock at the current DMA is written that contains 
information in the following form: 

f ind_buf_reserved DB 21 DUP (?) ; Reserved* 

attribute found 
time 
date 

low (size) 
high (size) 
13 DUP (?) ; packed name 



find buf attr 


DB 


? 


find buf time 


DW 


? 


find buf date 


DW 


? 


find buf size 1 


DW 


7 


find buf size h 


DW 


? 


find buf pname 


DB 


1 


find buf ENDS 







♦Reserved for MS-DOS use on subsequent find_next. 

To obtain the subsequent matches of the pathname, see th* 
description of Function 4FH. 

Error returns: 
AX 
2 * file not found 

The path specified in DS:DX was an invalid 

path. 
18 = no more files 

There were no files matching this 

specification. 
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Exaaple 



mov ah , 4EH 
Ids dx, pathname 
mov ex, attr 
int 21H 

; dma address has datablock 
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Step Through a Directory Hatching Files (Function 4FH) 



BX 
CX 
OX 



AH 


M. 


BH 


BL 


CH 


CI 


DH 


OL 



flagsh I fiAaan 



Call 

AH = 4FH 



Return 

Carry set: 
AX 

18 = no more files 
Carry not set: 

No error 



Function 4FH finds the next matching entry in a directory. 
The current DMA address must point at a block returned by 
Function 4EH (see Function 4EH) . 

Error returns: 

AX 

18 = no more files 

There are no more files matching this pattern. 



Example 



; dma points at area returned by Function 4FH 
mov ah, 4FH 
int 21H 

; next entry is at dma 
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Return Current Setting of Verify After Write Flag 
(Function 54H) 



am ;«. ] 


I)H 


* 1 


Cn 


CL j 


OH 


DL J 



FLAGS'* I FLAGSi 



Call 

AH = 5 4H 



Return 

AL 

Current verify flag value 



The current value of the verify flag is returned in AL. 



Error returns: 
None. 



Bxaaple 



mov ah,.54H 
int 21H 

; al is the current verify flag value 
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Hove a Directory Entry (Function 56H) 





AM 


i 


« 




6H 


1 


Bt 




CH 




CI ' 




DM 


! 
t 


» ! 




r 




SP 




r bp ! 


I 




Si 


...j 


I w i 




i .IP i 


1' 


LAGS 


- 


TIAO&, j 




! cs 


L 




DS 




ss j 


z. » J 



Call 

AH « 56R 
DS : DX 

Pointer to pathname of 

existing file 
ESrDI 

Pointer to new pathname 



Return 

Carry set: 

AX 

2 = file not found 
17 = not same device 
5 - access denied 

Carry not set: 
No error 



Function 5(5H attempts to rename a. file into another path, 
The paths must be on the same device. 

Error returns: 
AX 
2 = file not found 

The file name specif ed by DS:DX was not found. 
17 = not same device 

The source and destination are on different 

dr ives . 
5 = access denied 

The path specified in DS:DX was a directory or 

the file specified by ES:DI exists or the 

destination directory entry could not be 

created . 



Example 



Ids 


dx. 


source 


les 


di r 


dest 


mov 


ah , 


56H 


int 


21H 
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Get/Set Date/Ti»e of Pile (Function 57H) 

Call 



AH 


AL 


■M 


BL 


CM 


Ct 


OH 


DL 



AH 
AL 



57H 



FLAGS" | flAQh 



00 = get date and time 

01 = set date and time 
BX 

File handle 
CX (if AL = 01) 

Time to be set 
DX (if AL ■ 01) 

Date to be set 

Return 

Carry set: 
AX 

1 = invalid function 

6 = invalid handle 
Carry not set: 
No error 
CX/DX set if function 

Function 57H returns or sets the last-write time for a 
handle. These times are not recorded until the file is 
closed. 

A function code is passed in AL: 

AL Function 

Return the time/date of the handle in CX/DX 

1 Set the time/date of the handle to CX/DX 

Error returns: 
AX 
1 = invalid function 

The function passed in AL was not in the range 
0:1. 
6 = invalid handle 

The handle passed in Bx was not currently 
open. 



Example 



mov ah, 57H 
mov al, func 
mov bx, handle 

; if al =* 1 then then next two are mandatory 
mov ex, time 
mov dx, date 
int 21H 

; if al » then cx/dx has the last write time/date 

; for the handle. 
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1.8 MACRO DEFINITIONS FOR MS-DOS SYSTEM CALL EXAMPLES 



NOTE 



These macro definitions apply 
to system call examples 00H 
through 57H. 



.xlist 



******************* 

Interrupts 
******************* 



;ABS_DISK_READ 
abs disk read macro disk,buf fer , num sectors, first sector 



mov 

mov 

mov 

mov 

int 

popf 

endm 



al,disk 

bx, offset buffer 

ex , num_sectors 

dx, first sector 

37 



;interrupt 37 



;ABS_DISK_WRITE 
abs disk write macro disk,buf fer ,num sectors , first sector 



mov 

mov 

mov 

mov 

int 

popf 

endm 



al ,disk 

bx, offset buffer 

cx,num_sectors 

dx,f irst_sector 

38 



;interrupt 38 



; interrupt 39 



stay_resident macro last_instruc ;STAY_RESIDENT 
mov dx, offset last_instruc 
inc dx 
int 39 
endm 

******************* 

Functions 
******************* 

read kbd_and_echo macro 
mov ah , 1 
int 33 
endm 



; READ_KBD_AND_ECHO 
jfunction 1 



display_char macro character 

mov dl, character 



? DISPLAY CHAR 
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mov 


ah, 2 


int 


33 


endm 




aux input macro 




mov 


ah, 3 


int 


33 


endm 




aux output macro 




mov 


ah, 4 


int 


33 



endm 
; ;page 

printchar macro character 

mov dl, character 

mov ah , 5 

int 33 

endm 

dir_console_io macro switch 

mov dl, switch 

mov ah, 6 

int 33 
endm 

dir console input macro 



;function 2 



;AUX_INPUT 
jfunction 3 



; AUXJDUTPUT 
;function 4 



;PRINT_CHAR 
;function 5 

;DIR_CONSOLE_IO 
;function 6 

;DIR CONSOLE INPUT 





mov 
int 
endm 


ah, 7 
33 








;function 7 


read kbd 


macro 
mov 
int 
endm 


ah, 8 
33 








; READ_KBD 
;function 8 


9 

display 


macro 

mov 

mov 


string 
dx,of f set 
ah, 9 


str 


ing 


; DISPLAY 
.•function 9 




int 
endm 


33 










get string macro 
mov 
mov 
mov 
int 
endm 


limit ,str ing 
string , limit 
dx, offset str 
ah, 10 
33 


ing 


;GET_STRING 
;function 10 


check kbd 


status 
mov 


macro 
ah, 11 








;CHECK^KBD STATUS 
; function Tl 



int 33 
endm 



flush and read kbd macro switch 



; FLUSH AND READ KBD 
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tnov 


al , switch 






mov 


ah r 12 






int 


33 






endm 






» 

reset dis 


k macro 








mov 


ah, 13 






int 


33 






endm 






; ;page 








select disk macro 


disk 






mov 


dl,disk[-65] 




mov 


ah, 14 






int 


33 






endm 






open 


macro 


fcb 






mov 


dx,of f set 


fcb 




mov 


ah, 15 






int 


33 






endm 






close 


macro 


fcb 






mov 


dx,of f set 


fcb 




mov 


ah, 16 






int 


33 






endm 






search first macro 


fcb 






mov 


dx,of fset 


fcb 




mov 


ah, 17 






int 


33 






endm 






search next macro 


fcb 






mov 


dx,of f set 


fcb 




mov 


ah, 18 






int 


33 






endm 






delete 


macro 


fcb 






mov 


dx,of f set 


fcb 




mov 


ah, 19 






int 


33 






endm 






read_seq 


macro 


fcb 






mov 


dx,of f set 


fcb 




mov 


ah, 20 






int 


33 






endm 






write seq 


macro 


fcb 






mov 


dx,of f set 


fcb 




mov 


ah, 21 





^function 12 



; RESET DISK 
;function 13 



;SELECT_DISK 
;function 14 

;OPEN 
;function 15 

;CLOSE 
jfunction 16 

;SEARCH_FIRST 
.•Function 17 

;SEARCH_NEXT 
;function 18 

; DELETE 

; function 19 

;READ_SEQ 
; function 20 

;WRITE_SEQ 
^function 21 
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int 

en dm 

create macro 
mov 
mov 
int 
endm 

rename macro 
mov 
mov 
int 
endm 

r 

current_disk macro 

mov 

int 

endm 
» 
set_dta macro 

mov 

mov 

int 

endm 
» 
alloctable macro 

mov 

int 

endm 

read_ran macro 
mov 
mov 
int 
endm 

write ran macro 
mov 
mov 
int 
endm 

file_size macro 

mov 

mov 

int 

endm 
» 
set_relative_record 

mov 

mov 
int 33 

endm 
;;page 



33 



fcb 

dx, offset fcb 

ah, 22 

33 



fcb,newname 
dx, offset fcb 
ah, 23 
33 



ah, 25 
33 



buffer 

dx, offset buffer 

ah, 26 

33 



ah, 27 
33 



fcb 

dx, offset fcb 

ah, 33 

33 



fcb 

dx, offset fcb 

ah, 34 

33 



fcb 

dx, offset fcb 

ah, 35 

33 



macro fcb 
dx, offset fcb 
ah, 36 



j CREATE 
jfunction 22 

; RENAME 
;function 23 



;CURRENT_DISK 
;function 25 



;SET_DTA 
;function 26 



;ALLOC_TABLE 
; function 27 



; READ_RAN 
.•function 33 

;WRITE_RAN 
; function 34 

;FILE_SIZE 
;function 35 

; S ET_REL AT I VE_RECORD 
; function 36 
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set vector macro interrupt, seg addr,off addr ;SET VECTOR 



{function 37 



push 


ds 


mov 


ax,seg_addr 


mov 


ds,ax 


mov 


dx,off_addr 


mov 


al, interrupt 


mov 


ah ,37 


int 


33 


endm 





create_prog_seg macro seg_addr 
mov dx,seg_addr 
mov ah ,38 
int 33 
endm 



;CREATE_PROG_SEG 
; function 38 



ran block read macro fcb, count ,rec size ;RAN BLOCK READ 





mov 


dx, off set fcb 






mov 


ex, count 






mov 


word ptr fcb t 14] ,rec_size 






mov 


ah, 39 ; function 39 






int 


33 






endm 






• 
ran_block 


_wr i te 


macro fcb, count ,rec_size ; RAN_BLOCK_WF 


tlTl 




~mov 


dx, off set fcb 






mov 


ex, count 






mov 


word ptr fcb[14] ,rec size 






mov 


ah, 40 ; function 


40 




int 


33 






endm 






parse 


macro 


filename, fcb ; PARSE 






mov 


si, off set filename 






mov 


di, off set fcb 






push 


es 






push 


ds 






pop 


es 






mov 


al,15 






mov 


ah, 41 ; function 


41 




int 


33 






pop 


es 






endm 






get_date 


macro 


; GET_D ATE 






mov 


ah, 42 ;function 


42 




int 


33 






endm 






; ;page 








set_date 


macro 


year , month, day ;SET_DATE 






mov 


ex, year 






mov 


dh, month 






mov 


dl,day 






mov 


ah, 43 {function 


43 




int 


33 
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endm 



get time 


macro 






mov 


ah, 44 




int 


33 


i 


endm 




set time 


macro 


hour ,minutes, 




mov 


ch,hour 




mov 


cl, minutes 




mov 


dh, seconds 




mov 


dl , hundredths 




mov 


ah, 4 5 




int 


33 




endm 




# 

ver if y 


macro 


switch 




mov 


al , switch 




mov 


ah, 46 




int 


33 




endm 





;GET_TIME 
; function 44 



;SET_TIME 
edths 

/function 45 

; VERIFY 
/function 46 



******************* 

General 
******************* 



move_string macro source, destination, num_bytes 

yMOVE STRING 





push 


es 




mov 


ax,ds 




mov 


es,ax 




assume 


esrdata 




mov 


si, off set source 




mov 


di, off set destination 




mov 


cx,num bytes 


rep 


movs 


es: destination, source 




assume 


es: nothing 




pop 


es 


. 


endm 




» 
convert 


macro 


value, base, destination 




local 


table, start 




jmp 


start 


table 


db 


"0123456789ABCDEF" 


start: 


mov 


al, value 




xor 


ah, ah 




xor 


bx,bx 




div 


base 




mov 


bl,al 




mov 


al,cs: table fbx] 




mov 


destination, al 




mov 


bl,ah 




mov 


al,cs: table [bx] 



; CONVERT 
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mov 


destination [1] ,al 




endm 




? ;page 






convert 


to_binary 


macro str ing, number , value 






; CONVERT_TO_ BINARY 




local 


ten, start, calc, mul t,no_mult 




jmp- 


start 


ten 


db 


10 


start: 


mov 


value, 




xor 


ex, ex 




mov 


cl, number 




xor 


si ,si 


calc: 


xor 


ax, ax 




mov 


al,string[si] 




sub 


al,48 




cmp 


ex, 2 




jl 


no_mult 




push 


ex 




dec 


ex 


mult: 


mul 


cs: ten 




loop 


mult 




pop 


ex 


no_mult: 


add 


value, ax 




inc 


si 




loop 


calc 




endm 




convert 


date macro 


dir_entry 




mov 


dx,word ptr dir entry[25] 




mov 


cl,5 




shr 


dl,cl 




mov 


dh,dir entry[25] 




and 


dh,lfh 




xor 


ex, ex 




mov 


cl,dir entry[26] 




shr 


cl,l 




add 


ex, 1980 




endm 
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1.9 EXTENDED EXAMPLE OP MS-DOS SYSTEM CALLS 



title DISK DUMP 






zero 


equ 





disk_B 


equ 


1 


sectors per_read 


equ 


9 


cr 


equ 


13 


blank 


equ 


32 


period 


equ 


46 


tilde 


equ 


126 


INCLUDE BcCALLS.EQU 




SUbttl DATA SEGMENT 






page + 






data 


segment 


input_buf fer 


db 


9 dup(512 dup(?)) 


output_buf f er 


db 


77 dup(" ") 




db 


0DH,0AH,"$" 


startprompt 


db 


"Start at sector: $" 


sectors_prompt 


db 


"Number of sectors: $" 


continue_prompt 


db 


"RETURN to continue $" 


header 


db 


"Relative sector $" 


end_str ing 


db 


0DH,0AH r 0AH,07H,"ALL DONE$ 






; DELETE THIS 


crlf 


db 


0DH,0AH,"$" 


table 
* 


db 


"0123456789ABCDEF$" 


ten 


db 


10 


sixteen 


db 


16 


start_sector 


dw 


1 


sectornum 


label 


byte 


sector_number 


dw 





sectors_to_dump 


dw 


sectors per read 


sectors_read 


dw 





i 

buffer 


label 


byte 


max_length 


db 





current length 


db 





digits 


db 


5 dup(?) 


1 
data 


ends 


subttl STACK SEGMENT 






page + 






stack 


segment stack 




dw 


100 dup(?) 


stack_top 


label word 


stack 


ends 


subttl MACROS 






page + 
J 
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INCLUDE 


B 


5 CALLS 


.MAC 


; BLANK 


LINE 








blank_ 


Line 






macro 










local 
push 
call 
mov 


print_ 


it: 






display 

loop 

pop 










endm 


subttl 


ADDRESSABILITY 




page + 










code 








segment 
assume 


start: 








mov 
mov 
mov 
mov 
mov 



subttl PROCEDURES 
page + 

PROCEDURES 
READ_DISK 
read_disk 



get sector 



done: 
read_disk 
; CLEAR LINE 
clear Tine 



move blank: 



jmp 



number 
print_it 
ex 

clear_line 
ex, number 
output buffer 
print_Tt 
ex 



cs : code , ds : data ,ss:s tack 

ax, data 

ds,ax 

ax, stack 

ss,ax 

sp, off set stack_top 



main procedure 



proc; 




emp 


sec tor s_to_dump, zero 


jle 


done 


mov 


bx, offset input_buffer 


mov 


dx,start_sector 


mov 


al,disk_b 


mov 


ex , sector s_per_read 


emp 


ex , sector s_to_dump 


jle 


get sector 


mov 


cx,sectors_to_dump 


push 


ex 


int 


disk_read 


popf 




pop 


ex 


sub 


sectors_to_dump,cx 


add 


start_sector ,cx 


mov 


sectors_read,cx 


xor 


si ,si 


ret 




endp 




proc; 




push 


ex 


mov 


ex, 77 


xor 


bx,bx 


mov 


output buffertbx],' ' 


inc 


bx 
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clear line 
» 

;PUT_BLANK 
put blank 



put blank 



loop 
pop 
ret 
endp 



proc; 

raov 

inc 

ret 

endp 



move_blank 
ex 



output_buf fer [dil ," " 
di 



setup 



setup 

; CONVERT LINE 
convert line 



convert it: 



display_asci i : 

pr intable: 
non printable 

convert line 



proc; 

display start_prompt 

get_string 4 f buffer 

display crlf 

conver t_to_binary digits, 

cur rent_length, star t_scctor 

mov ax, star t_sector 

mov sector_number , ax 

display sectors prompt 

get_string 4,bufTer 

conver t_to_binary digits, 

current length , sector s_to_dump 

ret 

endp 



proc; 

push 

mov 

mov 

convert 

output_bu 

inc 

add 

call 

loop 

sub 

mov 

add 

mov 

emp 

jl 
emp 

jg 

mov 

mov 

inc 

inc 

loop 

pop 

ret 

endp 



ex 

di,9 
ex, 16 

input_buf fei. [sil .sixteen, 
f fer [dil 
si 

di,2 

put_blank 
convert_it 
si, 16 
ex, 16 
di,4 

outputbuf f er [dil .per iod 
input_buf fer [si 1 , blank 
non_pr intable 
input_buf f er [sil , ti lde 
non printable 
dl ,Tnput_buf f er [sil 
output_buf f er [dil »dl 
si 
di 

display_asci i 
ex 
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;DISPLAY_SCREEN 
display screen 



;I WANT length header 
;minus 1 in ex 
move header: 



dump it: 



display screen 



END PROCEDURES 
SUbttl MAIN PROCEDURE 
page + 

main_procedure: 
check done: 



display_it 

all_done: 
code 



proc; 

push 

call 



dec 

xor 
mov 
mov 
inc 
loop 



ex 

clear_line 

ex, 17 

ex 

di ,di 

al, header [di 1 

output_buf fer [di] ,al 

di 

move header ;FIX THIS! 



convert sector_num [ 1] , sixteen, 

output_buf fer [di] 

add di,2 

convert sector_num, sixteen, 

output_buf fer [di] 

display output_buf f er 

blank_line 2 

mov ex, 16 

call clear_line 

call convert line 

display output_Euf fer 

loop dump_it 

blank_line 3 

display continue_prompt 

get_char_no_echo 

display crlf 

pop ex 

ret 

endp 



call setup 

emp sectors_to_dump, zero 

jng all done 

call reacf_disk 

mov ex, sector s_read 

call display_screen 

call display_screen 

inc sector_number 

loop display_it 

jmp check_done 

display end_string 

get_char_no_echo 

ends 

end start 



CHAPTER 2 
MS-DOS 2.0 DEVICE DRIVERS 



2.1 WHAT IS A DEVICE DRIVER? 

A device driver is a binary file with all of the code in it 
to manipulate the hardware and provide a consistent 
interface to MS-DOS. In addition, it has a special header 
at the beginning that identifies it as a device, defines the 
strategv and interrupt entry points, and describes various 
attributes of the device. 



NOTE 

For device drivers, the file 
must not use the ORG 100H 
(like .COM files). Bec.-.jse it 
does not use the Ptogram 
Segment Prefix, the device 
driver is simply loaded; 
therefore, the file must have 
an origin of zero (ORG or no 
ORG statement) . 



There are two kinds of device drivers. 

1. Character device drivers 

2. Block device drivers 

Character devices are designed to perform serial character 
I/O like CON, AUX, and PRN . These devices are named (i.e., 
CON, AUX, CLOCK, etc.), and users may open channels (handles 
or FCBs) to do I/O to them. 

Block devices are the "disk drives" on the system. They can 
perform random I/O in pieces called blocks (usually the 
physical sector size). These devices are not named as the 
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character devices are, and therefore cannot be opened 
directly. Instead they are identified via the drive letters 
(A: , B: , C: , etc. ) . 

Block devices also have units. A single driver may be 
responsible for one or more disk drives. For example, block 
device driver ALPHA may be responsible for drives A:,B:,C: 
and D: . This means that it has four units (0-3) defined 
and, therefore, takes up four drive letters. The position 
of the driver in the list of all drivers determines which 
units correspond to which driver letters. If driver ALPHA 
is the first block driver in the device list, and it defines 
4 units (0-3), then they will be A:,B:,C: and D:. If BETA 
is the second block driver and defines three units (0-2) , 
then they will be E:,F: and G:, and so on. MS-DOS 2.0 is 
not limited to 16 block device units, as previous versions 
were. The theoretical limit is 63 (26 - 1), but it should 
be noted that after 26 the drive letters are unconventional 
(such as ] , \, and ~) . 



NOTE 

Character devices cannot 
define multiple units because 
they have only one name. 
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2.2 DEVICE HEADERS 



A device header is required at the beginning of 
driver. A device header looks like this: 



device 



DWORD pointer to next device 
(Must be set to -1) 



WORD attributes 

Bit 15 = 1 if char device is blk 

if bit 15 is 1 

Bit = 1 if current sti device 
Bit 1 = 1 if current sto output 
Bit 2 = I if current NUL device 
Bit 3 = 1 if current CLOCK dev 
Bit 4 = 1 if special 
Bits 5-12 Reserved; must be set 
to 

Bit 14 is the IOCTL bit 

Bit 13 is the NON IBM FORMAT bit 



WORD pointer to device strategy 
entry point 



WORD pointer to device interrupt 
entry point 



8-BYTE character device name field 
Character devices set a device name 
For block devices the first byte is 
the number of units 



Figure 2. Sample Device Header 

Note that the device entry points are words. They must be 
offsets from the same segment number used to point to this 
table. For example, if XXX:YYY points to the start of this 
table, then XXXrstrategy and XXX: inter rupt are the entry 
points. 



2.2.1 Pointer To Next Device Field 

The pointer to the next device header field is a double word 
field (offset followed by segment) that is set by MS-DOS to 
point at the next driver in the system list at the time the 
device driver is loaded. It is important that this field be 
set to -1 prior to load (when it is on the disk as a file) 
unless there is more than one device driver in the file. If 
there is more than one driver in the file, the first word of 
the double word pointer should be the offset of the next 
driver's Device Header. 
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NOTE 

If there is more than one 
device driver in the .COM 
file, the last driver in the 
file must have the pointer to 
the next Device Header field 
set to -1. 



2.2.2 Attribute Field 

The attribute field is used to tell the system whether this 
device is a block or character device (bit 15) . Most other 
bits are used to give selected character devices certain 
special treatment. (Note that these bits - mean nothing on a 
block device). For example, assume that a user has a new 
device driver that he wants to be the standard input and 
output. Besides installing the driver, he must tell MS-DOS 
that he wants his new driver to override the current 
standard input and standard output (the CON device) . This 
is accomplished by setting the attributes to the desired 
characteristics, so he would set bits and 1 to 1 (note 
that they are separate!). Similarly, a new CLOCK device 
could be installed by setting that attribute. (Refer to 
Section 2.7, "The CLOCK Device," in this chapter for more 
information.) Although there is a NUL device attribute, the 
NUL device cannot be reassigned. This attribute exists so 
that MS-DOS can determine if the NUL device is being used. 

The NON IBM FORMAT bit applies only to block devices and 

affects the operation of the BUILD BPB (Bios Parameter 

Block) device call. (Refer to Section 2.5.3, "MEDIA CHECK 

and BUILD BPB," for further information on this call). 

The other bit of interest is the IOCTL bit, which has 
meaning on character and block devices. This bit tells 
MS-DOS whether the device can handle control strings (via 
the IOCTL system call, Function 44H) . 

If a driver cannot process control strings, it should 
initially set this bit to 0. This tells MS-DOS to return an 
error if an' attempt is made (via Function 44H) to send or 
receive control strings to this device. A device which can 
process control strings should initialize the IOCTL bit to 
1. For drivers of this type, MS-DOS will make calls to the 
IOCTL INPUT and OUTPUT device functions to send and receive 
IOCTL strings. 

The IOCTL functions allow data to be sent and received by 
the device for its own use (for example, to set baud rate, 
stop bits, and form length) , instead of passing data over 
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the device channel as does a normal read or write. The 
interpretation of the passed information is up to the 
device, but it must not be treated as a normal I/O request. 



2.2.3 Strategy And Interrupt Routines 

These two fields are the pointers to the entry points of the 
strategy and interrupt routines. They are word values, so 
they must be in the same segment as the Device Header. 



2.2.4 Name Field 

This is an 8-byte field that contains the name of a 
character device or the number of units of a block device. 
If it is a block device, the number of units can be put in 
the first byte. This is optional, because MS-DOS will fill 
in this location with the value returned by the driver's 
INIT code. Refer to Section 2.4, "Installation of Device 
Drivers" in this chapter for more information. 



2.3 HOW TO CREATE A DEVICE DRIVER 

In order to create a device driver that MS-DOS can install, 
you must write a binarv file with a Device Header at the 
beginninq of the file. Note that for device drivers, the 
code should not be originated at 100H, but rather at 0. The 
link field (pointer to next Device Header) should be -1, 
unless there is more than one device driver in the file. 
The attribute field and entry points must be set correctly. 

If it is a character device, the name field should be filled 
in with the name of that character device. The name can be 
any legal 8-character filename. 

MS-DOS always processes installable device drivers before 
handling the default devices, so to install a new CON 
device, simply name the device CON. Remember to set the 
standard input device and standard output device bits in the 
attribute word on a new CON device. The scan of the device 
list stops on the first match, so the installable device 
driver takes precedence. 
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NOTE 

Because MS-DOS can install the 
driver anywhere in memory, 
care must be taken in any far 
memory references. You should 
not expect that your driver 
will always be loaded in the 
same place every time. 



2.4 INSTALLATION OP DEVICE DRIVERS 

MS-DOS 2.0 allows new device drivers to be installed 
dynamically at boot time. This is accomplished by INIT code 
in the BIOS, which reads and processes the CONFIG.SYS file. 

MS-DOS calls upon the device drivers to perform their 
function in the following manner: 

MS-DOS makes a far call to strategy entry, and 
passes (in a Request Header) the information 
describing the functions of the device driver. 

This structure allows you to program an interrupt-dr iven 
device driver. For example, you may want to perform local 
buffering in a printer. 



2.5 REQUEST- HEADER 

When MStDOS calls a device driver to perform a function, it 
passes a Request Header in ES:BX to the strategy entry 
point. This is a fixed length header, followed by data 
pertinent to the operation being performed. Note that it is 
the device driver's responsibility to preserve the machine 
state (for example, save all registers on entry and restore 
them on exit). There is enough room on the stack when 
strategy or interrupt is called to do about 20 pushes. If 
more stack is needed, the driver should set iip its own 
stack. 

The following figure illustrates a Request Header. 
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REQUEST HEADER -> 



BYTE length of record 
Length in bytes of this 
Request Header 



BYTE unit code 
The subunit the operation 
is for (minor device) 
(no meaning on character 
devices) 



BYTE command code 



WORD status 



8 bytes RESERVED 



Figure 3. Request Header 



2.5.1 Unit Code 

The unit code field identifies which unit in your device 
driver the request is for. For example, if your device 
driver has 3 units defined, then the possible values of the 
unit code field would be 0, 1, and 2. 



2.5.2 Command Code Field 

The command code field in the Request header can have the 
following values: 



Command 
Code 



Function 



INIT 

1 MEDIA CHECK (Block only, NOP for character) 

2 BUILD BPB " " " " " 

3 IOCTL INPUT (Only called if device has IOCTL) 

4 INPUT (read) 

5 NON- DESTRUCTIVE INPUT NO WAIT (Char devs only) 

6 INPUT STATUS 

7 INPUT FLUSH " ' " 

8 OUTPUT (write) 

9 OUTPUT (Write) with verify 

10 OUTPUT STATUS " " " 

11 OUTPUT FLUSH 

12 IOCTL OUTPUT (Only called if device has IOCTL) 
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2.5.3 MEDIA CHECK And BUILD BPB 

MEDIA CHECK and BUILD BPB are used with block devices only. 



MS-DOS calls MEDIA CHECK first for a drive unit. MS-DOS 
passes its current media descriptor byte (refer to the 
section "Media Descriptor Byte" later in this chapter) . 
MEDIA CHECK returns one of the following results: 

Media Not Changed - current DPB and media byte are 
OK. 

Media Changed - Current DPB and media are wrong. 
MS-DOS invalidates any buffers for this unit and 
calls the device driver to build the BPB with media 
byte and buffer. 

Not Sure - If there are dirty buffers (buffers with 
changed data, not yet written to disk) for this 
unit, MS-DOS assumes the DPB and media byte are OK 
(media not changed) . If nothing is dirty, MS-DOS 
assumes the media has changed. It invalidates any 
buffers for the unit, and calls the device driver 
to build the BPB with media byte and buffer. 

Error - If an error occurs, MS-DOS sets the error 
code accordingly. 



MS-DOS will call BUILD BPB under the following conditions: 

If Media Changed is returned 

If Not Sure is returned, and there are no dirty 
buffers 



The BUILD BPB call also gets a pointer to a one-sector 
buffer. What this buffer contains is determined by the NON 
IBM FORMAT bit in the attribute field. If the bit is zero 

(device is IBM format-compatible) , then the buffer contains 
the first sector of the first FAT. The FAT ID byte is the 
first' byte of this buffer. NOTE: The BPB must be the same, 
as far as location of the FAT is concerned, for all possible 
media because this first FAT sector must be read before the 
actual BPB is returned. If the NON IBM FORMAT bit is set, 
then the pointer points to one sector of scratch space 

(which may be used for anything) . 
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2.5.4 Status Word 

The following figure illustrates the status word in the 
Request Header. 



15 14 13 12 11 10 



E 


1 l 1 ■ 1 
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D 




R 


RESERVED 


U 





ERROR CODE (bit 15 on) 


R 


> » l l 


S 


N 


1 t i < i t i 



The status word is zero on entry and is set by the driver 
interrupt routine on return. 

Bit 8 is the done bit. When set, it means the operation is 
complete. For MS-DOS 2.0, the driver sets it to 1 when it 
exits. 

Bit 15 is the error bit. If it is set, then the low 8 bits 
indicate the error. The errors are: 

Write protect violation 

1 Unknown Unit 

2 Drive not ready 

3 Unknown command 

4 CRC error 

5 Bad drive request structure length 

6 Seek error 

7 Unknown media 

8 Sector not found 

9 Printer out of paper 
A Write fault 

B Read Fault 

C General failure 

Bit 9 is the busy bit, which is set only by status calls. 

For output on character devices; If bit 9 is 1 on 
return, a write request (if made) would wait for 
completion of a current request. If it is 0, there 
is no current request, and a write request (if 
made) would start immediately. 
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F° r input on char a cter devices with a buffer ; If 
bit 9 is 1 on return, a read request (if made) 
would go to the physical device. If it is on 
return, then there are characters in the device 
buffer and a read would return quickly. It also 
indicates that something has been typed. MS-DOS 
assumes all character devices have an input 
type-ahead buffer. Devices that do not have a 
type-ahead buffer should always return busy=0 so 
that MS-DOS will not continuously wait for 
something to get into a buffer that does not exist. 

One of the functions defined for each device is INIT. This> 
routine is called only once when the device is installed. 
The INIT routine returns a location (DS:DX) , which is a 
pointer to the first free byte of memory after the device 
driver (similar to "Keep Process"). This pointer method can 
be used to delete initialization code that is only needed 
once, saving on space. 

Block devices are installed the same way and also return a 
first free byte pointer as described above. Additional 
information is also returned: 

The number of units is returned. This determines 
logical device names. If the current maximum 
logical device letter is F at the time of the 
install call, and the INIT routine returns 4 as the 
number of units, then they will have logical names 
G, H, I and J. This mapping is determined by the 
position of the driver in the device list, and by 
the number of units on the device (stored in the 
first byte of the device name field) . 

A pointer to a BPB (BIOS Parameter Block) pointer 
array is also returned. There is one table for 
each unit defined. These blocks will be used to 
build an internal DOS data structure for each of 
the units. The pointer passed to the DOS from the 
driver points to an array of n word pointers to 
BPBs, where n is the number of units defined. In 
this way, if all units are the same, all of the 
pointers can point to the same BPB, saving space. 
Note that this array must be protected (below the 
free pointer set by the return) since an internaL 
DOS structure will be built starting at the byte 
pointed to by the free pointer. The sector size 
defined must be less than or equal to the maximum 
sector size defined at default BIOS INIT time. If 
it isn't, the install will fail. 

The last thing that INIT of a block device must 
pass back is the media descriptor byte. This byte 
means nothing to MS-DOS, but is passed to devices 
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so that they know what parameters MS-DOS is 
currently using for a particular drive unit. 

Block devices may take several approaches; they may be dumb 
or srn_a r_t . A dumb device defines a unit (and therefore an 
interna"! DOS structure) for each possible media drive 
combination. For example, unit = drive single side, 
unit 1 = drive double side. For this approach, media 
descriptor bytes do not mean anything. A smart device 
allows multiple media per unit. In this case, the BPB table 
returned at INIT must define space large enough to 
accommodate the largest possible media supported. Smart 
drivers will use the media descriptor byte to pass 
information about what media is currently in a unit. 



2.6 FUNCTION CALL PARAMETERS 

All strategy routines are called with ES:BX pointing to the 
Request Header. The interrupt routines get the pointers to 
the Request Header from the queue that the strategy routines 
store them in. The command code in the Request Header tells 
the driver which function to perform. 



NOTE 

All DWORD pointers are stored 
offset first, then segment. 



MS-DOS 2.0 DEVICE DRIVERS 



Page 2-12 



2.6.1 INIT 



Command code = 
INIT - ES.-BX -> 



13-BYTE Request Header 



BYTE # of units 



DWORD break address 



DWORD pointer to BPB array 
(Not set by character devices) 



The number of units, break address, and BPB pointer are set 
by the driver. On entry, the DWORD that is to be set to the 
BPB array (on block devices) points to the character after 
the '=' on the line in CONFIG.SYS that loaded this device. 
This allows drivers to scan the CONFIG.SYS invocation line 
for arquments. 



NOTE 

If there are multiple device 
drivers in a single .COM file, 
the ending address returned by 
the last INIT called will be 
the one MS-DOS uses. It is 
recommended that all of the 
device drivers in a single 
.COM file return the same 
ending address. 



2.6.2 MEDIA CHECK 



Command Code = 1 
MEDIA CHECK - ES:BX -> 



13-BYTE 



Request Header 



BYTE media descriptor from DPB 



BYTE returned 
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In addition to setting the status word, the driver must set 
the return byte to one of the following: 

-1 Media has been changed 

Don't know if media has been changed 

1 Media has not been changed 

If the driver can return -1 or 1 (by having a door-lock or 
other interlock mechanism) MS-DOS performance is enhanced 
because MS-DOS does not need to reread the FAT for each 
directory access. 



2.6.3 BUILD BPB (BIOS Parameter Block) 



Command code = 2 



BUILD BPB - ES:BX -> 



13-BYTE Request Header 



BYTE media descriptor from DPB 



DWORD transfer address 

(Points to one sector worth of 
scratch space or first sector 
of FAT depending on the value 
of the NON IBM FORMAT bit) 



DWORD pointer to BPB 



If the NON IBM FORMAT bit of the device is set, then the 
DWORD transfer address points to a one sector buffer, which 
can be used for any purpose. If the NON IBM FORMAT bit is 
0, then this buffer contains the first sector of the first 
FAT and the driver must not alter this buffer. 



If IBM compatible format is used (NON IBM FORMAT BIT = 0) , 
then the first sector of the first FAT must be located at 
the same sector on all possible media. This is because the 
FAT sector will be read BEFORE the media is actually 
determined. Use this mode if all you want is to read the 
FAT ID byte. 



In addition to setting status word, the driver must set 
Pointer to the BPB on return. 



the 
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In order to allow for many different OEMs to read each 
other's disks, the following standard is suggested: The 
information relating to the BPB for a particular piece of 
media is kept in the boot sector for the media. In 
particular, the format of the boot sector is: 



3 BYTE near JUMP to boot code 



8 BYTES OEM name and version 



WORD bytes per sector 



BYTE sectors per allocation unit 



WORD reserved sectors 



BYTE number of FATs 



WORD number of root dir entries 



WORD number of sectors in logical 
image 



BYTE media descriptor 



WORD number of FAT sectors 



WORD sectors per track 



WORD number of heads 



WORD number of hidden sectors 



The three words at the end (sectors per track, number of 
heads, and number of hidden sectors) are optional. They are 
intended to help the BIOS understand the media. Sectors per 
track may be redundant (could be calculated from total size 
of the disk) . Number of heads is useful for supporting 
different multi-head drives which have the same storage 
capacity, but different numbers of surfaces. Number of 
hidden sectors may be used to support drive-partitioning 
schemes. 
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2.6.4 Media Descriptor Byte 

The last two digits of the FAT ID byte are called the media 
descriptor byte. Currently, the media descriptor byte has 
been defined for a few media types, including 5-1/4" and 8" 
standard disks. For more information, refer to Section 3.6, 
"MS-DOS Standard Disk Formats." 

Although these media bytes map directly to FAT ID bytes 
(which are constrained to the 8 values F8-FF) , media bytes 
can, in general, be any value in the. range 0-FF. 
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2.6.5 READ Or WRITE 



Command codes = 3,4,8,9, and 12 

READ or WRITE - ES:BX (Including IOCTL) -> 



13-BYTE Request Header 



BYTE media descriptor from DPB 



DWORD transfer address 



WORD byte/sector count 



WORD starting sector number 
(Ignored on character devices) 



In addition to setting the status word, the driver must set 
the sector count to the actual number of sectors (or bytes) 
transferred. No error check is performed on an IOCTL I/O 
call. The driver must correctly set the return sector 
(byte) count to the actual number of bytes transferred. 

THE FOLLOWING APPLIES TO BLOCK DEVICE DRIVERS: 



Under certain circumstances the BIOS may be 
a write operation of 64K bytes, which se 
around" of the transfer address in the B 
This request arises due to an optimiza 
write code in MS-DOS. It will only manifes 
that are within a sector size of 64K 
"growing" past the current EOF. It is al 
BIOS to igno re the bala n ce of the writ e th~ 
*£ ±t f*S± choo ses . For example, a write 
worth of sectors with a transfer addre 
ignore the last two bytes. A user program 
an I/O of more than FFFFH bytes and cannot 
to 0) in the transfer segment. Therefore, 
last two bytes can be ignored. 



asked to perforin 
ems to be a "wrap 
IOS I/O packet, 
tion added to the 
t on user writes 
bytes on files 
lowable for the 
at "wrap s a round" 
of 10000H bytes 
ss of XXX: 1 could 
can never request 
wrap around (even 
in this case, the 
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2.6.6 NON DESTRUCTIVE READ NO WAIT 



Command code = 5 

NON DESRUCTIVE READ NO WAIT - ES:BX -> 



13-BYTE Request Header 



BYTE read from device 



If the character device returns busy bit = (characters in 
buffer), then the next character that would be read is 
returned. This character is not removed from the input 
buffer (hence the term "Non Destructive Read"). Basically, 
this call allows MS-DOS- to look ahead one input character. 
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2.6.7 STATUS 



Command codes = 6 and 10 
STATUS Calls - ES:BX -> 



13-BYTE Request Header 



All the driver must do is set the status word and the busy 
bit as follows: 

Fo r output on character d evices ; If bit 9 is 1 on 
return, a write request (if made) would wait for 
completion of a current request. If it is 0, there 
is no current request and a write request (if made) 
would start immediately. 



For input on character devices wi 
return of 1 means; a read reque 
go to the physical device. If it 
then there are characters in the 
a read would return quickly. A r 
indicates that the user has 
MS-DOS assumes that all character 
input type-ahead buffer. Device 
a type-ahead buffer should always 
so that the DOS will not hang wai 
to get into a buffer which doesn' 



th a buffer : A 
st '.if made) would 

is on return, 
devices buffer and 
eturn of also 

typed something. 

devices have an 
s that do not have 

return busy = 
ting for something 
t exist. 



2.6.8 FLUSH 



Command codes = 7 and 11 
FLUSH Calls - ES:BX -> 



13-BYTE Request Header 



The FLUSH call tells the driver to 
pending requests. This call is 
queue on character devices. 



flush (terminate) all 
used to flush the input 
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2.7 THE CLOCK DEVICE 

One of the most popular add-on boards is the real time clock 
board. To allow this board to be integrated into the system 
for TIME and DATE, there is a special device (determined by 
the attribute word) called the CLOCK device. The CLOCK 
device defines and performs functions like any other 
character device. Most functions will be: "set done bit, 
reset error bit, return." When a read or write to this 
device occurs, exactly 6 bytes are transferred. The first 
two bytes are a word, which is the count of days since 
1-1-80. The third byte is minutes; the fourth, hours; the 
fifth, hundredths of seconds; and the sixth, seconds. 
Reading the CLOCK device gets the date and time; writing to 
it sets the date and time. 
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2.8 EXAMPLE OP DEVICE DRIVERS 

The following examples illustrate a block device driver and 
a character device driver program. 



2.8.1 Block Device Driver 

.ft******************** a BLOCK DEVICE ******************* 
TITLE 5 1/4" DISK DRIVER FOR SCP DISK-MASTER 

;This driver is intended to drive up to four 5 1/4" drives 
; hooked to the Seattle Computer Products DISK MASTER disk 
;controller. All standard IBM PC formats are supported. 



FALSE EQU 

TRUE EQU NOT FALSE 

;The I/O port address of the DISK MASTER 

DISK EQU 0E0H 

;DISK+0 

; 1793 Command/Status 

;DISK+1 

1793 Track 
;DISK+2 

; 1793 Sector 
;DISK+3 

; 1793 Data 
;DISK+4 

; Aux Command/Status 
;DISK+5 
; Wait Sync 

;Back side select bit 
BACKBIT EQU 04H 
;5 1/4" select bit 
SMALBIT EQU 10H 
;Double Density bit 
DDBIT EQU 08H 

;Done bit in status register 
DONEBIT EQU 01H 

Use table below to select head step speed. 

Step times for 5" drives 

are double that shown in the table. 

Step value 1771 1793 

6ms 3ms 

1 6ms 6ms 
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2 




10ms 


10ms 


; 3 




20ms 


15ms 


STPSPD 


EQU 


1 




NUMERR 


EQU 


ERROUT- 


-ERRI 


CR 


EQU 


ODH 




LF 


EQU 


OAH 





CODE SEGMENT 

ASSUME CS : CODE , DS : NOTHING , ES : NOTHING , SS : NOTHING 



DEVICE HEADER 



DRVDEV 


LABEL 


WORD 






DW 


-1,-1 






DW 


0000 


;IBM format-compatible, Block 




DW 


STRATEGY 






DW 


DRV$IN 




DRVMAX 


DB 


4 




DRVTBL 


LABEL 


WORD 






DW 


DRV$INIT 






DW 


MEDIA$CHK 






DW 


GET$BPB 






DW 


CMDERR 






DW 


DRV$READ 


• 




DW 


EXIT 






DW 


EXIT 






DW 


EXIT 






DW 


DRV$WRIT 






DW 


DRV$WRIT 






DW 


EXIT 






DW 


EXIT 






DW 


EXIT 






STRATEGY 




PTRSAV 


DD 







ST RAT P 


PROC 


FAR 




STRATEGY: 








MOV 


WORD PTR 


[PTRSAV] ,BX 




MOV 


WORD PTR 


(PTRSAV+21 ,ES 




RET 






STRATP 


ENDP 








MAIN ENTRY 
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CMDLEN 


= 





UNIT 


= 


1 


CMDC 


= 


2 


STATUS 


= 


3 


MEDIA 


= . 


13 


TRANS 


= 


14 


COUNT 


= 


18 


START 


= 


20 


DRV$IN: 








PUSH 


SI 




PUSH 


AX 




PUSH 


CX 




PUSH 


DX 




PUSH 


DI 




PUSH 


BP 




PUSH 


DS 




PUSH 


ES 




PUSH 


BX 



LENGTH OF THIS COMMAND 

SUB UNIT SPECIFIER 

COMMAND CODE 

STATUS 

MEDIA DESCRIPTOR 

TRANSFER ADDRESS 

COUNT OF BLOCKS OR CHARACTERS 

FIRST BLOCK TO TRANSFER 



LDS 



BX, [PTRSAV1 



MOV 


AL,BYTE 


PTR 


[BX1 


.UNIT 


MOV 


AH, BYTE 


PTR 


[BX] 


.MEDIA 


MOV 


CX,WORD 


PTR 


[BX1 


.COUNT 


MOV 


DX,WORD 


PTR 


[BX] 


.START 


PUSH 


AX 








MOV 


AL,BYTE 


PTR 


[BX] 


.CMDC 


CMP 


AL,ll 








J A 


CMDERRP 








CBW 










SHL 


AX, I 








MOV 


SI , OFFSET DRVTBL 




ADD 


SI ,AX 








POP 


AX 









;GET POINTER TO I/O PACKET 

;AL = UNIT CODE 

;AH = MEDIA DESCRIP 

;CX = COUNT 

;DX = START SECTOR 

;Command code 

;Bad command 

;2 times command = 
;word table index 

;Index into table 
;Get back media 
; and unit 



LES 



DI, DWORD PTR [BX1 .TRANS ;ES:DI = TRANSFER 

; ADDRESS 



PUSH 

pop- 



es 

DS 



ASSUME DSrCODE 

JMP WORD PTR [SI] 



;G0 DO COMMAND 



EXIT - ALL ROUTINES RETURN THROUGH THIS PATH 



ASSUME DS: NOTHING 
CMDERRP: 
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CMDERR: 



POP 

MOV 
JMP 



AX 

AL,3 

SHORT ERRSEXIT 



;Clean stack 

; UNKNOWN COMMAND ERROR 



ERR$CNT:LDS 
SUB 



BX, [PTRSAV1 

WORD PTR fBX] . COUNT, CX ; # OF SUCCESS. I/Os 



ERRSEXIT: 

;AL has error code 

MOV AH,10000001B 



EXITP 

EXIT: 
ERR1: 



JMP 

PROC 

MOV 
LDS 
MOV 



POP 
POP 
POP 
POP 
POP 
POP 
POP 
POP 
POP 
RET 
ENDP 



EXITP 

CURDRV DB 

TRKTAB DB 

SECCNT DW 

DRVLTM = 

SECLIM = 
HDLIM 



;MARK ERROR RETURN 



SHORT ERRl 

FAR 

AH,00000001B 

BX, [PTRSAV] 

WORD PTR [BX] .STATUS, AX 

;MARK OPERATION COMPLETE 

BX 
ES 
DS 
BP 
DI 
DX 
CX 
AX 
SI 

; RESTORE REGS AND RETURN 



-1 

-1 ,-1,-1,-1 



8 ;Number of sectors on device 
13 ; MAX I MUM SECTOR 
15 ; MAXIMUM HEAD 



;WARNING - preserve order of drive and curhd! 



DRIVE 


DB 





PHYSICAL DRIVE CODE 


CURHD 


DB 





CURRENT HEAD 


CUR SEC 


DB 





CURRENT SECTOR 


CURTRK 


DW 





CURRENT TRACK 



MEDIASCHK: 

ASSUME DS:CODE 

TEST AH,00000100B 
JZ MEDIA$EXT 



; Always indicates Don't know 

;TEST IF MEDIA REMOVABLE 



MS-DOS 2.0 DEVICE DRIVERS 


XOR 


DI,DI ;SA 


MEDIA$EXT: 




LDS 


BX, [PTRSAV] 


MOV 


WORD PTR [BX] .TRANS, DI 


JMP 


EXIT 
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I DON'T KNOW 



BUILD$BPB: 
ASSUME DS:CODE 



SETBPB: 



BUILDBP 
ASSUME 
;AH is 
;DI poi 



MOV 

CALL 

LDS 

MOV 

MOV 

MOV 

JMP 



AH, BYTE PTR ES : 
GETBP 

BX, [PTRSAV] 
[BX] .MEDIA, AH 
[BX] . COUNT, DI 
[BX] .COUNT+2,CS 
EXIT 



[DI1 



;GET FAT ID BYTE 
; TRANSLATE 



DS: NOTHING 
media byte on entry 
nts to correct BPB on 



return 



GOODID: 



HAS8: 



HAS! 



PUSH 

PUSH 

PUSH 

PUSH. 

MOV 

AND 

CMP 

JZ 

MOV 



MOV 

MOV 

MOV 

MOV 

MOV 

TEST 

JNZ 

INC 

INC 

ADD 

TEST 

JZ 

ADD 

MOV 

INC 

INC 

MOV 

MOV 

MOV 

MOV 

MOV 

MOV 

MOV 

POP 



AX 

CX 

DX 

BX 

CL,AH 

CL,0F8H 

CL,0F8H 

GOODID 

AH,0FEH 



AL,1 

BX, 64*256 

CX,40*8 

DX, 01*256 

DI , OFFSET 

AH, 000000 

HAS 8 

AL 

BL 

CX,40 

AH, 000000 

HASl 

CX,CX 

BH,112 

DH 

DL 

BYTE PTR 

BYTE PTR 

WORD PTR 

BYTE PTR 

BYTE PTR 

BYTE PTR 

BYTE PTR 

BX 



;SAVE MEDIA 

;NORMALIZE 

;COMPARE WITH GOOD MEDIA BYTE 

; DEFAULT TO 8-SECTOR, 
; SINGLE-SIDED 

;SET NUMBER OF FAT SECTORS 
+8 ;SET DIR ENTRIES AND SECTOR MAX 

;SET SIZE OF DRIVE 
+1 ;SET HEAD LIMIT h SEC/ALL UNIT 

DRVBPB 
10B ;TEST FOR 8 OR 9 SECTOR 

;NZ = HAS 8 SECTORS 

;INC NUMBER OF FAT SECTORS 

;INC SECTOR MAX 

;INCREASE SIZE 
0LB ;TEST FOR 1 OR 2 HEADS 

;Z = 1 HEAD 

;DOUBLE SIZE OF DISK 

; INCREASE # OF DIREC. ENTRIES 

;INC SEC/ALL UNIT 

; INC HEAD LIMIT 
[DT] . 2,DH 
[DI] .6,BH 
[DI] .8,CX 
[DI1 .10, AH 
[DI] .ll.AL 
[DI] .13,BL 
[DI].15,DL 
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POP 


DX 


POP 


CX 


POP 


AX 


RET 





ENTRY! 



EXIT: 



DISK I/O HANDLERS 



AL = DRIVE NUMBER (0-3) 

AH = MEDIA DESCRIPTOR 

CX * SECTOR COUNT 

DX = FIRST SECTOR 

DS = CS 

ES:DI = TRANSFER ADDRESS 

IF SUCCESSFUL CARRY FLAG = 

ELSE CF=1 AND AL CONTAINS (MS-DOS) ERROR CODE, 
CX # sectors NOT transferred 



DRV$READ: 
ASSUME DS:CODE 



JCXZ DSKOK 

CALL SETUP 

JC DSK$IO 

CALL DISKRD 



JMP 



SHORT DSK$IO 



DRV$WRIT: 

ASSUME DS:CODE 

JCXZ DSKOK 
CALL SETUP 
JC DSK$IO 
CALL DISKWRT 

ASSUME DS: NOTHING 

DSK$IO: JNC DSKOK 

JMP ERR$CNT 

DSKOK: JMP EXIT 



SETUP: 

ASSUME DS:CODE 
Input same as above 
On output 
ES:DI = Trans addr 
DS:BX Points to BPB 

Carry set if error (AL is error code (MS-DOS)) 
else 

[DRIVE] = Drive number (0-3) 
[SECCNT] = Sectors to transfer 
[CURSEC] = Sector number of start of I/O 
[CURHD] = Head number of start of I/O 



;Set 



(CURTRK] » Track # of start of I/O ;Seek performed 
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; All other registers destroyed 



XCHG 

CALL 

MOV 

ADD 

CMP 

JBE 
MOV 
STC 
RET 



;ES:BX = TRANSFER ADDRESS 
;DS:DI = PTR TO B.P.B 



BX f DI 
GETBP 
SI,CX 
SI.DX 
SI, WORD PTR [DI].DRVLIM 

;COMPARE AGAINST DRIVE MAX 
INRANGE 
AL,8 



INRANGE: 



SEEK: 



TRYSK: 



NOHOMEi 



MOV 
MOV 
XCHG 

XOR 
DIV 
INC 
MOV 
MOV 
XOR 
DIV 
MOV 
MOV 

PUSH 

PUSH 

CALL 

CALL 

MOV 

XOR 

ADD 

MOV 

MOV 

XCHG 

OUT 

CMP 

JZ 

MOV 

CMP 

JNZ 

CALL 
JC 

MOV 

OUT 

MOV 

CALL 

AND 

JZ 

JS 



[DRIVE] , AL 

[SECCNT] ,CX ;SAVE SECTOR COUNT 
AX,DX ;SET UP LOGICAL SECTOR 

;FOR DIVIDE 
DX,DX 

WORD PTR [DI] .SECLIM ; DIVIDE BY SEC PER TRACK 
DL 

[CURSEC] ,DL ;SAVE CURRENT SECTOR 

CX,WORD PTR [DI].HDLIM ;GET NUMBER OF HEADS 
DX,DX ; DIVIDE TRACKS BY HEADS PER CYLINDER 
CX 

[CURHD] f DL ;SAVE CURRENT HEAD 
[CURTRK] ,AX ;SAVE CURRENT TRACK 



;Xaddr 

;BPB pointer 

;Unload head if change drives 



BX 

DI 

CHKNEW 

DRIVESEL 

BL, [DRIVE] 

BH,BH ;BX drive index 

BX, OFFSET TRKTAB ;Get current track 

AX, [CURTRK] 

DL,AL ;Save desired track 

AL,DS: [BX] ;Make desired track current 

DISK+1,AL ;Tell Controller current track 

AL,DL ?At correct track? 

SEEKRET ;Done if yes 

BH,2 ;Seek retry count 

AL,-1 ; Posit ion Known? 

NOHOME ;If not home head 

HOME 
SEEKERR 

AL/DL 

DISK+3,AL 

AL,1CH+STPSPD 

DCOM 

AL,98H ;Accept not rdy, seek, & CRC errors 

SEEKRET 

SEEKERR ;No retries if not ready 



;Desired track 
;Seek 
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SEEKERR: 



DEC BH 

JNZ TRYSK 

MOV BL, [DRIVE] 

XOR BH,BH ;BX drive index 

ADD BX, OFFSET TRKTAB ;Get current track 

MOV BYTE PTR DS : [BX] ,-1 ;Make current track 

; lunknown 

CALL GETERRCD 

MOV CX,[SECCNT] ;Nothing transferred 

POP BX ;BPB pointer 

POP DI ;Xaddr 

RET 



SEEKRET: 



POP 
POP 
CLC 
RET 



BX 

DI 



;BPB pointer 
;Xaddr 



READ 



DISKRD: 






ASSUME 


DS : CODE 




MOV 


CX, [SECCNT] 


RDLP: 








CALL 


PRESET 




PUSH 


BX 




MOV 


BL,10 




MOV 


DX,DISK+3 


RDAGN : 








MOV 


AL,80H 




CLI 






OUT 


DISK,AL 




MOV 


BP,DI 




JMP 


SHORT RLOOPENTRY 


RLOOP: 


STOSB 




RLOOPENTRY : 






IN 


AL,DISK+5 




SHR 


AL,1 




IN 


AL,DX 




JNC 


RLOOP 




ST I 






CALL 


GET ST AT 




AND 


AL,9CH 




JZ 


RDPOP 




MOV 


DI,BP 




DEC 


BL 




JNZ 


RDAGN 




CMP 


AL,10H 




JNZ 


GOT CODE 



;Retry count 
;Data port 

;Read command 
;Disable for 1793 
;Output read command 
;Save address for retry 



;Wait for DRQ or INTRQ 
?Read data 
;Ints OK now 



;Ok 

;Get back transfer 



; Record not found? 
;No 
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MOV 



GOT CODE: 



RDPOP: 



AL,1 



CALL GETERRCD 

POP BX 

RET 



POP BX 
LOOP RDLP 
CLC 
RET 



;Map it 



WRITE 



DISKWRT 


: 




ASSUME 


DS:CODE 






MOV 


CX, fSECCNT] 




MOV 


SI,DI 




PUSH 


ES 




POP 


DS 


ASSUME 


DS: NOTHING 


WRLP: 








CALL 


PRESET 




PUSH 


BX 




MOV 


BL,10 




MOV 


DX,DISK+3 


WRAGN : 








MOV 


AL,0A0H 




CLI 






OUT 


DISK,AL 




MOV 


BP,SI 


WRLOOP : 








IN 


AL,DISK+5 




SHR 


AL r l 




LODSB 






OUT 


DX f AL 




JNC 


WRLOOP 




ST I 






DEC 


SI 




CALL 


GETSTAT 




AND 


AL , OFCH 




JZ 


WRPOP 




MOV 


SI,BP 




DEC 


BL 




JNZ 


WRAGN 




CALL 


GETERRCD 




POP 


BX 




RET 




WRPOP: 







;Retry count 
;Data port 

;Write command 
;Disable for 1793 
;Output write command 
;Save address for retry 



;Get data 
;Write data 

;Ints OK now 



;Ok 

;Get back transfer 



POP 



BX 
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LOOP WRLP 

CLC 

RET 



PRESET! 
ASSUME 



DS: NOTHING 



SETHEAD: 



GOTSEC: 



MOV 

CMP 

JBE 

MOV 

INC 

CMP 

JB 

CALL 

XOR 

MOV 
CALL 
MOV 
MOV 

OUT 
INC 
RET 



AL, [CURSEC] 

AL,CS: [BX] .SECLIM 

GOTSEC 

DH, [CURHD] 

DH 

DH,CS: [BX] .HDLIM 

SETHEAD 

STEP 

DH,DH 

(CURHD ] ,DH 
DRIVESEL 
AL,1 

[CURSEC] ,AL 



;Select new head 
;Go on to next track 
;Select head zero 



;First sector 
;Reset CURSEC 



DISK+2,AL ;Tell controller which sector 
[CURSEC] ;We go on to next sector 



STEP : 
ASSUME 



DS: NOTHING 

MOV AL,58H+STPSPD ;Step in w/ update, no verify 

CALL DCOM 

PUSH BX 

MOV BL, [DRIVE] 

XOR BH,BH ;BX drive index 

ADD BX, OFFSET TRKTAB ;Get current track 

INC BYTE PTR CS: [BX] ;Next track 

POP BX 

RET 



HOME: 
ASSUME 

TRYHOM : 



HOMERR: 



DS: NOTHING 
MOV BL , 3 



MOV 

CALL 

AND 

JZ 

JS 

PUSH 

MOV 

CALL 

DEC 

POP 

JNZ 

STC 



AL,0CH+STPSPD 

DCOM 

AL,98H 

RET3 

HOMERR 

AX 

AL,58H+STPSPD 

DCOM 

BL 

AX 

TRYHOM 



;Restore with verify 



;No retries if not ready 

;Save real error code 

;Step in w/ update no verify 



;Get back real error code 
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RET 3: 



RET 



CHKNEW: 
ASSUME 



DS: NOTHING 



;Get disk drive number 



MOV AL,[DRIVE1 

MOV AH , AL 

XCHG AL, [CURDRV] ;Make new drive current. 

CMP AL,AH ;Changing drives? 

JZ RET1 ;No 

If changing drives, unload head so the head load delay 
one-shot will fire again. Do it by seeking to the same 
track with the H bit reset. 



;Get current track number 
;Make it the track to seek 
;Seek and unload head 





IN 


AL,DISK+1 




OUT 


DISK+3,AL 




MOV 


AL,10H 


DCOM: 






ASSUME 


DS: NOTHING 




OUT 


DISK,AL 




PUSH 


AX 




AAM 






POP 


AX 


GETSTAT 


• 






IN 


AL,DISK+4 




TEST 


AL,DONEBIT 




JZ 


GETSTAT 




IN 


AL,DISK 


RET1: 


RET 





;Delay 10 microseconds 



DRIVESEL: 

ASSUME DS: NOTHING 

;Select the drive based on current info 

;Only AL altered 

MOV AL, [DRIVE] 

OR AL,SMALBIT + DDBIT ;5 1/4" IBM PC disks 

CMP [CURHD] ,0 

JZ GOTHEAD 

OR AL, BACKBIT ;Select side 1 



GOTHEAD: 



OUT 
RET 



DISK+4,AL 



;Select drive and side 



GETERRCD : 

ASSUME DS: NOTHING 



PUSH CX 

PUSH ES 

PUSH DI 

PUSH CS 

POP ES ;Make ES the local segment 

MOV CS: fLSTERR] ,AL ;Terminate list w/ error code 

MOV CX,NUMERR ;Number of error conditions 

MOV DI, OFFSET ERRIN ;Point to error conditions 

REPNE SCASB 
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MOV 
STC 
POP 
POP 
POP 
RET 



AL,NUMERR-l[DIl 

DI 
ES 
CX 



;Get translation 
;Flag error condition 



;and return 



********************************************************* 
BPB FOR AN IBM FLOPPY DISK, VARIOUS PARAMETERS ARE 
PATCHED BY GETBP TO REFLECT THE TYPE OF MEDIA 
INSERTED 
This is a nine sector single side BPB 

;Physical sector size in bytes 
;Sectors/allocation unit 
.•Reserved sectors for DOS 
;# of allocation tables 
;Number directory entries 
;Number 512-byte sectors 
;Media descriptor 
; Number of FAT sectors 
;Sector limit 
;Head limit 



;Up to four units 



DRVBPB: 








DW 


512 




DB 


1 




DW 


1 




DB 


2 




DW 


64 




DW 


9*40 




DB 


11111100B 




DW 


2 




DW 


9 




DW 


1 


INJTAB 


DW 


DRVBPB 




DW 


DRVBPB 




DW 


DRVBPB 




DW 


DRVBPB 


ERRIN: 


;DISK 


ERRORS RETU 




DB 


80H 




DB 


40H 




DB 


20H 




DB 


10H 




DB 


8 




DB 


1 


LSTERR 


DB 





ERROUT : 


; RETURNED ERROR C( 




DB 


2 




DB 







DB 


OAH 




DB 


6 




DB 


4 




DB 


8 




DB 


12 



;NO RESPONSE 

;Write protect 

;Write Fault 

;SEEK error 

;CRC error 

;Mapped from 10H 

; (record not found) on READ 

;ALL OTHER ERRORS 



;NO RESPONSE 

;WRITE ATTEMPT 

;ON WRITE-PROTECT DISK 

;WRITE FAULT 

;SEEK FAILURE 

;BAD CRC 

; SECTOR NOT FOUND 

;GENERAL ERROR 



DRV$INIT: 

Determine number of physical drives by reading CONFIG.SYS 
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ASSUME DS:CODE 

PUSH DS 

LDS SI,[PTRSAV] 
ASSUME DS: NOTHING 

LDS SI, DWORD PTR [SI .COUNT] ;DS:SI points to 

; CONFIG. SYS 



SCANJLOOP : 






CALL 


SCAN SWITCH 




MOV 


AL,CL 




OR 


AL,AL 




JZ 


SCAN 4 




CMP 


AL,"S" 




JZ 


SCAN 4 


WERROR: 


POP 


DS 


ASSUME 


DStCODE 






MOV 


DX, OFFSET ERRMSG2 


WERROR 2- 


: MOV 


AH r 9 




INT 


21H 




XOR 


AX, AX 




PUSH 


AX 




JMP 


SHORT ABORT 


BADNDRV 


: 






POP 


DS 




MOV 


DX, OFFSET ERRMSG1 




JMP 


WERROR2 



;No units 



SCAN 4: 

ASSUME DS: NOTHING 

;BX is number of floppies 
OR BX,BX 
JZ BADNDRV 
CMP BX,4 
JA BADNDRV 
POP DS 

ASSUME DS:CODE 

PUSH BX 

ABORT: LDS BX,[PTRSAV] 

ASSUME DS: NOTHING 



POP 
MOV 
MOV 
MOV 

MOV 
MOV 

MOV 
JMP 



AX 



;User error 
;User error 

;Save unit count 



;Unit count 



BYTE PTR [BX] .MEDIA, AL 
[DRVMAX] ,AL 
WORD PTR [BX] .TRANS, OFFSET DRV$INIT ;SET 

; BREAK ADDRESS 
[BX] .TRANS+2,CS 
WORD PTR [BX] .COUNT, OFFSET INITAB 

;SET POINTER TO BPB ARRAY 
[BX] .COUNT+2,CS 
EXIT 



PUT SWITCH IN CL, VALUE IN BX 
BX,BX 



SCAN_SWITCH 
XOR 
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MOV 


CX,BX 


LODSB 




CMP 


AL,10 


JZ 


NUMRET 


CMP 


AL,"-" 


JZ 


GOT SWITCH 


CMP 


AL,"/" 


JNZ 


SCAN_SWITCH 


GOT SWITCH: 




CMP 


BYTE PTR [SI+1] ," 


JNZ 


TERROR 


LODSB 




OR 


AL,20H 


MOV 


CL,AL ; 


LODSB 





CONVERT TO LOWER CASE 
GET SWITCH 
SKIP ":" 



GET NUMBER POINTED TO BY [SI] 



WIPES OUT AX,DX ONLY 



BX RETURNS NUMBER 



GETNUM1 


: LODSB 






SUB 


AL,"0" 




JB 


CHKRET 




CMP 


AL,9 




JA 


CHKRET 




CBW 






XCHG 


AX,BX 




MOV 


DX,10 




MUL 


DX 




ADD 


BX,AX 




JMP 


GETNUM1 


CHKRET: 


ADD 


AL,"0" 




CMP 


AL," " 




JBE 


NUMRET 




CMP 


AL,"-" 




JZ 


NUMRET 




CMP 


AL,"/" 




JZ 


NUMRET 


TERROR: 








POP 


DS 




JMP 


WERROR 


NUMRET : 


DEC 
RET 


SI 


ERRMSG1 


DB 


"SMLDRV 


ERRMSG2 


DB 


"SMLDRV 


CODE 


ENDS 
END 





; GET RID OF RETURN ADDRESS 



"SMLDRV: Bad number of drives", 13, 10,"$' 
"SMLDRV: Invalid parameter ", 13 , 10 , "$" 
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2.8.2 Character Device Driver 

The following program illustrates a character device driver 
program. 



•A******************* ^ CHARACTER DEVICE ******************* 
TITLE VT52 CONSOLE FOR 2.0 (IBM) 
> . . ....................................... ..••«..•......... 

• IBM ADDRESSES FOR I/O 



CR=13 ; CARRIAGE RETURN 

BACKSP=8 .-BACKSPACE 

ESC=1BH 

BRKADR=6CH ;006C BREAK VECTOR «VDDRESS 

ASNMAX=200 ;SIZE OF KEY ASSIGNMK^T BUFFER 

CODE SEGMENT BYTE 

ASSUME CS : CODE , DS : NOTHING , ES : NOTHING 



CON- CONSOLE DEVICE DRIVER 

CONDEV: ; HEADER FOR DEVICE "CON" 

DW -1,-1 

DW 1000000000010011B ;CON IN AND CON OUT 

DW STRATEGY 

DW ENTRY 

DB 'CON 



COMMAND JUMP TABLES 
CONTBL : 



DW 


CON$INIT 


DW 


EXIT 


DW 


EXIT 


DW 


CMDERR 


DW 


CON $ READ 


DW 


CON$RDND 


DW 


EXIT 


DW 


CON$FLSH 


DW 


CON$WRIT 


DW 


CON$WRIT 


DW 


EXIT 


DW 


EXIT 


CMDTABL DB 


'A' 
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PAGE 



DW 


CUU 


DB 


'B' 


DW 


CUD 


DB 


•c 


DW 


CUF 


DB 


•D' 


DW 


CUB 


DB 


»H' 


DW 


CUH 


DB 


'J' 


DW 


ED 


DB 


•K' 


DW 


EL 


DB 


•Y' 


DW 


CUP 


DB 


'J' 


DW 


PSCP 


DB 


•k' 


DW 


PRCP 


DB 


•y. 


DW 


RM 


DB 


•x' 


DW 


SM 


DB 


00 



Device entry point 



;cursor up 
; cursor down 
;cursor forward 
;cursor back 
•cursor position 
;erase display 
;erase line 
;cursor position 
;save cursor position 
;restore cursor position 
;reset mode 
;set mode 



CMDLEN 


= 





UNIT 


= 


1 


CMD 


= 


2 


STATUS 


= 


3 


MEDIA 


= 


13 


TRANS 


= 


14 


COUNT 


= 


18 


START 


= 


20 


PTRSAV 


DD 






LENGTH OF THIS COMMAND 

SUB UNIT SPECIFIER 

COMMAND CODE 

STATUS 

MEDIA DESCRIPTOR 

TRANSFER ADDRESS 

COUNT OF BLOCKS OR CHARACTERS 

FIRST BLOCK TO TRANSFER 



ST RAT P PROC 



FAR 



STRATEGY : 






MOV 


WO 




MOV 


WO 




RET 




ST RAT P 


ENDP 




ENTRY: 








PUSH 


SI 




PUSH 


AX 




PUSH 


CX 




PUSH 


DX 



WORD PTR CS: [PTRSAV] ,BX 
WORD PTR CS: [PTRSAV+2] ,ES 
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PUSH 
PUSH 
PUSH 
PUSH 
PUSH 

LDS 

MOV 

MOV 
CBW 
MOV 
ADD 
ADD 
CMP 
JA 

LES 

PUSH 
POP 

ASSUME 

JMP 



DI 
BP 
DS 
ES 
BX 

BX,CS: [PTRSAV] ;GET POINTER TO I/O PACKET 

CX,WORD PTR DS: [BX] .COUNT ;CX = COUNT 

AL,BYTE PTR DS:[BX].CMD 

SI, OFFSET CONTBL 

SI, AX 

SI, AX 

AL,11 

CMDERR 

DI, DWORD PTR DS: [BX] .TRANS 



CS 
DS 



DS:CODE 

WORD PTR [SI1 



;GO DO COMMAND 



PAGE 



SUBROUTINES SHARED BY MULTIPLE DEVICES 



BUS$EXIT: 

MOV 
JMP 



EXIT - ALL ROUTINES RETURN THROUGH THIS PATH 

; DEVICE BUSY EXIT 



CMDERR: 



MOV 



ERR$EXIT: 

MOV 
JMP 

PROC 



EXITP 
EXIT: 

cr\r\ 1 ! 



AH,00000011B 
SHORT ERR1 



AL,3 



AH,10000001B 
SHORT ERR1 

FAR 



; UNKNOWN COMMAND ERROR 
;MARK ERROR RETURN 



MOV 
LDS 
MOV 



AH,00000001B 

BX,CS: [PTRSAV] 

WORD PTR [BX] .STATUS, AX ;MARK 

; OPERATION COMPLETE 
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POP 


BX 


POP 


ES 


POP 


DS 


POP 


BP 


POP 


DI 


POP 


DX 


POP 


CX 


POP 


AX 


POP 


SI 


RET 




EXITP ENDP 





; RESTORE REGS AND RETURN 



BREAK KEY HANDLING 



BREAK : 

MOV 
I NT RET: I RET 



CS : ALT AH , 3 



; INDICATE BREAK KEY SET 



PAGE 



WARNING - Variables are very order dependent, 
so be careful when adding new ones! 



= WRAP, 1 = NO WRAP 



WRAP 


DB 





STATE 


DW 


SI 


MODE 


DB 


3 


MAXCOL 


DB 


79 


COL 


DB 





ROW 


DB 





SAVCR 


DW 





ALTAH 


DB 






;Special key handling 



CHROUT - WRITE OUT CHAR IN AL USING CURRENT ATTRIBUTE 



.•CHARACTER ATTRIBUTE 
;BASE PAGE 



ATTRW 


LABEL 


WORD 


ATTR 


DB 


00000111B 


BPAGE 


DB 





base 


dw 


0b800h 


chrout: 


cmp 


al,13 




jnz 


trylf 




mov 


Icol] ,0 




jmp 


short setit 


trylf: 


cmp 


al,10 




jz 


If 




cmp 


al,7 




jnz 


tryback 


torom: 








mov 


bx, [attrw] 




and 


bl,7 




mov 


ah, 14 
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int 


lOh 


ret5: 


ret 




tryback 


: 






cmp 


al,8 




jnz 


outchr 




cmp 


[col] ,0 




jz 


ret5 




dec 


[col] 




jmp 


short setit 


outchr : 








mov 


bx, [attrw] 




mov 


cx,l 




mov 


ah, 9 




int 


lOh 




inc 


[col] 




mov 


al r fcol] 




cmp 


al , [maxcol] 




jbe 


setit 




cmp 


[wrap] ,0 




jz 


outchrl 




dec 


[col] 




ret 




outchrl 


: 






mov 


[col 1,0 


If: 


inc 


[row] 




cmp 


[rowj ,24 




jb 


setit 




mov 


[row] ,23 




call 


scroll 


setit:. 


mov 


dh,row 




mov 


dl,col 




xor 


bh,bh 




mov 


ah, 2 




int 


lOh 




ret 




scroll: 


call 


getmod 




cmp 


al,2 




jz 


myscroll 




cmp 


al,3 




jz 


myscroll 




mov 


al,10 




jmp 


torom 


myscroll: 






mov 


bh, [attr] 




mov 


bl,' • 




mov 


bp,80 




mov 


ax, [base] 




mov 


es,ax 




mov 


ds,ax 




xor 


di,di 




mov 


si ,160 
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mov 


ex, 23*80 


eld 




emp 


ax,0b800h 


jz 


colorcard 


rep 


movsw 


mov 


ax,bx 


mov 


cx,bp 


rep 


stosw 


sret: push 


cs 


pop 


ds 


ret 




colorcard: 




mov 


dx,3dah 


wait2: in 


al ,dx 


test 


al,8 


jz 


wait2 


mov 


al,25h 


mov 


dx,3d8h 


out 


dx,al 


rep 


movsw 


mov 


ax,bx 


mov 


cx,bp 


rep 


stosw 


mov 


al,29h 


mov 


dx,3d8h 


out 


dx,al 


jmp 


sret 


GETMOD: MOV 


AH, 15 


INT 


16 


MOV 


BPAGE,BH 


DEC 


AH 


MOV 


WORD PTR MODE, AX 


RET 





;turn off video 



;turn on video 



;get column information 



CONSOLE READ ROUTINE 



CON $ READ: 




JCXZ 


CON $ EX IT 


CON $ LOOP: 




PUSH 


CX 


CALL 


CHRIN 


POP 


CX 


STOSB 




LOOP 


CON$LOOP 


CON$EXIT: 




JMP 


EXIT 



.•SAVE COUNT 
;GET CHAR IN AL 

; STORE CHAR AT ES:DI 



INPUT SINGLE CHAR INTO AL 
CHRIN: XOR AX, AX 
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XCHG 


AL,ALTAH 




OR 


AL r AL 




JNZ 


KEYRET 


INAGN : 


XOR 


AH, AH 




INT 


22 


ALT 10: 








OR 


AX, AX 




JZ 


INAGN 




OR 


ALrAL 




JNZ 


KEYRET 




MOV 


ALT AH, AH 


KEYRET : 


RET 





;GET CHARACTER & ZERO ALT AH 



;Check for non-key after BREAK 
^SPECIAL CASE? 

; STORE SPECIAL KEY 



KEYBOARD NON DESTRUCTIVE READ, NO WAIT 



CON$RDND: 






MOV 


AL, [ALT AH] 




OR 


AL.AL 




JNZ 


RDEXIT 


RD1: 


MOV 


AH,1 




INT 


22 




JZ 


CONBUS 




OR 


AX, AX 




JNZ 


RDEXIT 




MOV 


AH,0 




INT 


22 




JMP 


CON$RDND 


RDEXIT: 


LDS 


BX, [PTRSAV] 




MOV 


[BX] . MEDIA, AL 


EXVEC: 


JMP 


EXIT 


CONBUS : 


JMP 


BUS$EXIT 



KEYBOARD PLUSH ROUTINE 



CON$FLSH: 






MOV 


fALTAHl ,0 ;Clear 


out holding buffer 


PUSH 


DS 




XOR 


BP,BP 




MOV 


DS,BP 


;Select segment 


MOV 


DSrBYTE PTR 41AH,1EH 


;Reset KB queue head 
jpointer 


MOV 


DS:BYTE PTR 41CH,1EH 


;Reset tail pointer 


POP 


DS 




JMP 


EXVEC 




; CONSOLE 


WRITE ROUTINE 





CON $ WRIT: 
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JCXZ EXVEC 

PUSH CX 

MOV AH , 3 

XOR BX,BX 

INT 16 

MOV WORD PTR [COL] ,DX 

POP CX 



;SET CURRENT CURSOR POSITION 



CON $ LP: MOV 
INC 
CALL 
LOOP 
JMP 



AL,ES: [DI] 

DI 

OUTC 

CON$LP 

EXVEC 



J GET CHAR 

; OUTPUT CHAR 

; REPEAT UNTIL ALL THROUGH 



COUT: 



STI 

PUSH 

PUSH 

POP 

CALL 

POP 

I RET 



DS 

CS 

DS 

OUTC 

DS 



OUTC: 



PUSH 

PUSH 

PUSH 

PUSH 

PUSH 

PUSH 

PUSH 

CALL 

POP 

POP 

POP 

POP 

POP 

POP 

POP 

RET 



AX 

CX 

DX 

SI 

DI 

ES 

BP 

VIDEO 

BP 

ES 

DI 

SI 

DX 

CX 

AX 



OUTPUT SINGLE CHAR IN AL TO VIDEO DEVICE 

VIDEO: MOV SI, OFFSET STATE 
JMP [SI] 



SI: 



CMP 
JNZ 
MOV 
RET 



AL,ESC 

SIB 

WORD PTR [SI], OFFSET S2 



; ESCAPE SEQUENCE? 



SIB: 
S1A: 



CALL 

MOV 

RET 



CHROUT 

WORD PTR [STATE] , OFFSET SI 
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S2: 


PUSH 


AX 






CALL 


GETMOD 






POP 


AX 






MOV 


BX, OFFSET 


' CMDTABL-3 


S7A: 


ADD 


BX f 3 






CMP 


BYTE PTR 


[BX] ,0 




JZ 


S1A 






CMP 


BYTE PTR 


[BX] ,AL 




JNZ 


S7A 






JMP 


WORD PTR 


[BX+1] 


MOVCUR: 


CMP 


BYTE PTR 


[BX] ,AH 




JZ 


SETCUR 






ADD 


BYTE PTR 


[BX] ,AL 


SETCUR: 


MOV 


DX,WORD PTR COL 




XOR 


BX,BX 






MOV 


AH, 2 






INT 


16 






JMP 


S1A 




CUP: 


MOV 
RET 


WORD PTR 


[SI] , OFFSET CUPl 


CUP1: 


SUB 


AL,32 






MOV 


BYTE PTR 


[ROW] ,AL 




MOV 


WORD PTR 


[SI] , OFFSET CUP2 




RET 






CUP2: 


SUB 


AL,32 






MOV 


BYTE PTR 


[COL] ,AL 




JMP 


SETCUR 




SM: 


MOV 
RET 


WORD PTR 


[SI] , OFFSET S1A 


CUH: 


MOV 


WORD PTR 


COL,0 




JMP 


SETCUR 




CUF: 


MOV 


AH ,MAXCOL 


i 




MOV 


AL,1 




CUFl: 


MOV 


BX, OFFSET 


' COL 




JMP 


MOVCUR 




CUB: 


MOV 


AX,00FFH 






JMP 


CUFl 




CUU: 


MOV 


AX,00FFH 




CUU1: 


MOV 


BX, OFFSET 


ROW 




JMP 


MOVCUR 




CUD: 


MOV 


AX, 23*256+1 




JMP 


CUU1 
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PSCP: 


MOV 


AX , WORD PTR COL 




MOV 


SAVCR,AX 




JMP 


SETCUR 


PRCP: 


MOV 


AX , SAVCR 




MOV 


WORD PTR COL, AX 




JMP 


SETCUR 


ED: 


CMP 


BYTE PTR I ROW] ,24 




JAE 


ELI 




MOV 


CX,WORD PTR COL 




MOV 


DH,24 




JMP 


ERASE 


ELI: 


MOV 


BYTE PTR [COL] ,0 


EL: 


MOV 


CX,WORD PTR [COL] 


EL 2: 


MOV 


DH,CH 


ERASE: 


MOV 


DL,MAXCOL 




MOV 


BH,ATTR 




MOV 


AX,0600H 




INT 


16 


•ED 3: 


JMP 


SETCUR 


RM: 


MOV 
RET 


WORD PTR ISI] , OFFSET RMl 


RMl: 


XOR 


CX,CX 




MOV 


CH,24 




JMP 


EL 2 


CON$INIT: 






int 


llh 




and 


al, 00110000b 




cmp 


al, 00110000b 




jnz 


iscolor 




mov 


[base] , ObOOOh ;lo 


iscolor 


: 






cmp 


al, 00010000b ;lo 




ja 


setbrk 




mov 


[mode] ,0 




mov 


. [maxcol],39 


setbrk: 








XOR 


BX,BX 




MOV 


DS,BX 




MOV 


BX,BRKADR 




MOV 


WORD PTR [BX] , OFFSET BREAK 




MOV 


WORD PTR [BX+2] ,CS 




MOV 


BX,29H*4 




MOV 


WORD PTR [BX] , OFFSET COUT 




MOV 


WORD PTR [BX+2] ,CS 



;look for bw card 
;look for 40 col mode 
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LDS BX,CS: [PTRSAV] 

MOV WORD PTR [BX] .TRANS , OFFSET CON$INIT 

;SET BREAK ADDRESS 
MOV (BX] .TRANS+2,CS 
JMP EXIT 

CODE ENDS 
END 



CHAPTER 3 
MS-DOS TECHNICAL INFORMATION 



3.1 MS-DOS INITIALIZATION 

MS-DOS initialization consists of several steps. Typically, 
a ROM (Read Only Memory) bootstrap obtains control, and then 
reads the boot sector off the disk. The boot sector then 
reads the following files: 

10. SYS 
MSDOS.SYS 

Once these files are read, the boot process begins. 



3.2 THE COMMAND PROCESSOR 

The command processor supplied with MS-DOS (file 
C0MMAND.COM.) consists of 3 parts: 



A resident part resides in memory immediately 
following MSDOS.SYS and its data area. This part 
contains routines to process Interrupts 23H 
(CONTROL-C Exit Address) and 24H (Fatal Error Abort 
Address) , as well as a routine to reload the 
transient part, if needed. All standard MS-DOS 
error handling is done within this part of 
C0MMAND.COM. This includes displaying error 
messages and processing the Abort, Retry, or Ignore 
messages. 



An initialization part follows the resident part. 
During startup, the initialization part is given 
control; it contains the AUTOEXEC file processor 
setup routine. The initialization part determines 
the segment address at which programs can be 
loaded. It is overlaid by the first program 
C0MMAND.COM loads because it is no longer needed. 
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3. A transient part is loaded at the high end of 
memory. This part contains all of the internal 
command processors and the batch file processor. 

The transient part of the command processor 
produces the system prompt (such as A>) , reads the 
command from keyboard (or batch file) and causes it 
to be executed. For external commands, this part 
builds a command line and issues the EXEC system 
call (Function Request 4BH) to load and transfer 
control to the program. 
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3.3 MS-DOS DISK ALLOCATION 

The MS-DOS area is formatted as follows: 



Reserved area - variable size 



First copy of file allocation 
table - variable size 



Second copy of file allocation 
table - variable size (optional) 



Additional copies of file alloca- 
tion table-variable size (opt.) 



Root directory - variable size 



File data area 



Allocation of space for a file 
pre-allocated. The space is 



in the data area is 
allocated one cluster 



time. A cluster 

sectors; all of 

together in the 

to Section 3.5, 

usually a second 

Should the disk 

first FAT, the second can be used. 

due to an unusable disk. 



consists of one or more consec 

the clusters for a file are "cha 

File Allocation Table (FAT) . ( 

"File Allocation Table.") The 

copy of the FAT kept, for consist 

develop a bad sector in the middle o 

This avoids loss of 



not 
at a 
utive 
ined" 
Refer 
re is 
ency . 
f the 
data 



3.4 MS-DOS DISK DIRECTORY 

FORMAT builds the root directory for all disks. Its 
location on disk and the maximum number of entries are 
dependent on the media. 

Since directories other than the root directory are regarded 
as files by MS-DOS, there is no limit to the number of files 
they may contain. 

All directory entries are 32 bytes in length, and are in the 
following format (note that byte offsets are in 
hexadecimal) : 
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0-7 Filename. Eight characters, left aligned and 
padded, if necessary, with blanks. The first 
byte of this field indicates the file status 
as follows: 

00H The directory entry has never been 
used. This is used to limit the 
length of directory searches, for 
performance reasons. 

2EH The entry is for a directory. If 
the second byte is also 2EH, 
then the cluster field contains 
the cluster number of this 
directory's parent directory 
(0000H if the parent directory 
is the root directory) . Other- 
wise, bytes 01H through OAH 
are all spaces, and the cluster 
field contains the cluster 
number of this directory. 

E5H The file was used, but it has been 
erased. 

Any other character is the first character 
of a filename. 

8-,0A Filename extension. 

OB File attribute. The attribute byte is 
mapped as follows (values are in hexa- 
decimal) : 

01 File is marked read-only. An attempt 
to open the file for writing using 
the Open File system call (Function 
Request 3DH) results in an error 
code being returned. This value 

can be used along with other 
values below. Attempts to delete 
the file with the Delete File 
system call (13H) or Delete a 
Directory Entry (41H) will also 
fail. 

02 Hidden file. The file is excluded 
from normal directory searches. 

04 System file. The file is excluded 
from normal directory searches. 

08 The entry contains the volume label 
in the first 11 bytes. The entry 
contains no other usable information 
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{except date and time of creation) , 
and may exist only in the root 
directory. 

10 The entry defines a sub-directory, 
and is excluded from normal 
directory searches. 

20 Archive bit. The bit is set to "on" 
whenever the file has been written 
to and closed. 

Note: The system files (10. SYS and 
MSDOS.SYS) are marked as read-only, 
hidden, and system files. Files can 
be marked hidden when they are created. 
Also, the read-only, hidden, system, 
and archive attributes may be changed 
through the Change Attributes system 
call (Function Request 43H) . 

OC-15 Reserved. 

16-17 Time the file was created or last updated. 
The hour, minutes, and seconds are mapped 
into two bytes as follows: 

Offset 17H 
|h|h|h|h|h|m|m|m| 

7 3 2 

Offset 16H 

|m|m|m|s|s|s|s|s| 

5 4 

where: 

H is the binary number of hours (0-23) 
M is the binary number of minutes 

(0-59) 
S is the binary number of two-second 

increments 

18-19 Date the file was created or last updated. 

The year, month, and day are mapped into two bytes 
as follows: 

Offset 19H 

|y|y|y|y|y|y|y|m. | 
7 10 

Offset 18H 
|m|m|m|d|d|d|d|d| 

5 4 
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where: 

Y is 0-119 (1980-2099) 
M is 1-12 
D is 1-31 

1A-1B Starting cluster; the cluster number 
of the first cluster in the file. 

Note that the first cluster for data space 
on all disks is cluster 002. 

The cluster number is stored with the 
least significant byte first. 



NOTE 

Refer to Section 3.5.1, 
"How to Use the File 
Allocation Table," for details 
about converting cluster 
numbers to logical sector 
numbers. 



1C-1F File size in bytes. The first word of this 
four-byte field is the low-order part of 
the size. 
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3.5 FILE ALLOCATION TABLE (FAT) 

The following information is included for system programmers 
who wish to write installable device drivers. This section 
explains how MS-DOS uses the File Allocation Table to 
convert the clusters of a file to logical sector numbers. 
The driver is then responsible for locating the logical 
sector on dis'k. Programs must use the MS-DOS file 
management function calls for accessing files; programs 
that access the FAT are not guaranteed to be 
upwardly-compatible with future releases of MS-DOS. 

The File Allocation Table is an array of 12-bit entries (1.5 
bytes) for each cluster on the disk. The first 'two FAT 
entries map a portion of the directory; these FAT entries 
indicate the size and format of the disk. 

The second and third bytes currently always contain FFH. 

The third FAT entry, which starts at byte offset 4, begins 
the mapping of the data area (cluster 002) . Files in the 
data area are not always written sequentially on the disk. 
The data area is allocated one cluster at a time, skipping 
over clusters already allocated. The first free cluster 
found w.ill be the next cluster allocated, regardless of its 
physical location on the disk. This permits the most 
efficient utilization of disk space because clusters made 
available by erasing files can be allocated for new files. 

Each FAT entry contains three hexadecimal characters: 



000 If the cluster is unused and available. 

FF7 The cluster has a bad sector in it. 

MS-DOS will not allocate such a cluster. 
CHKDSK counts the number of bad clusters 
for its report. These bad clusters are 
not part of any allocation chain. 

FF8-FFF Indicates the last cluster of a file. 

XXX Any other characters that are 

the cluster number of the next cluster in 
the file. The cluster number of the first 
cluster in the file is kept in the file's 
directory entry. 

The File Allocation Table always begins on the first section 
after the reserved sectors. If the FAT is larger than one 
sector, the sectors are continguous. Two copies of the FAT 
are usually written for data integrity. The FAT is read 
into one of the MS-DOS buffers whenever needed (open, read, 
write, etc.). For performance reasons, this buffer is given 
a high priority to keep it in memory as long as possible. 
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3.5.1 How To Ose The Pile Allocation Table 

Use the directory entry to find the starting cluster of the 
file. Next, to locate each subsequent cluster^ of the file: 



1. Multiply the cluster number just used by 1.5 (each 
FAT entry is 1.5 bytes long). 



2. The whole part of the product is an offset into the 
FAT, pointing to the entry that maps the cluster 
just used. That entry contains the cluster number 
of the next cluster of the file. 



3. Use a MOV instruction to move the word at the 
calculated FAT offset into a register. 



If the last cluster used was an even number, keep 
the low-order 12 bits of the register by ANDing it 
with FFF; otherwise, keep the high-order 12 bits 
by shifting the register right 4 bits with a SHR 
instruction. 



5. If the resultant 12 bits are FF8H-FFFH, the file 
contains no more clusters. Otherwise, the 12 bits 
contain the cluster number of the next cluster in 
the file. 



To convert the cluster to a logical sector number (relative 
sector, such as that used by Interrupts 25H and 26H and by 
DEBUG) : 

1. Subtract 2 from the cluster number. 



2. Multiply the result by the number of sectors per 
cluster . 



3. Add to this result the logical sector number of the 
beginning of the data area. 
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3.6 MS-DOS STANDARD DISK PORMATS 

On an MS-DOS disk, the clusters are arranged on disk to 
minimize head movement for multi-sided media. All of the 
space on a track (or cylinder) is allocated before moving on 
to the next track. This is accomplished by using the 
sequential sectors on the lowest-numbered head, then all the 
sectors on the next head, and so on until all sectors on all 
heads of the track are used. The next sector to be used 
will be sector 1 on head of the next track. 

For disks, the following table can be used: 



# 


Sectors/ 


FAT size 


Dir 


Dir 


Sectors/ 


Sides 


Track 


Sectors 


Sectors 


Entries 


Cluster 


1 


8 


1 


4 


64 


1 


2 


8 


1 


7 


112 


2 


1 


9 


2 


4 


64 


1 


2 


9 


2 


7 


112 


2 



Figure 4. 5-1/4" Disk Format 



The first byte of the FAT can sometimes be used to determine 
the format of the disk. The following 5-1/4" formats have 
been defined for the IBM Personal Computer, based on values 
of the first byte of the FAT. The formats in Table 3.1 are 
considered to be the standard disk formats for MS-DOS. 
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Table 3.1 MS-DOS Standard Disk Formats 

5-1/4 5-1/4 5-1/4 5-1/4 8 8 8 



No. sides 


1 


1 


2 


2 


1 


1 


2 


Tracks/side 


40 


40 


40 


40 


77 


77 


77 


Bytes/ 
sector 


512 


512 


512 


512 


128 


128 


1024 


Sectors/ 
track 


8 


9 


8 


9 


26 


26 


8 


Sectors/allo- 
cation unit 


1 


1 


2 


2 


4 


4 


1 


Reserved 
sectors 


1 


1 


1 


1 


1 


4 


1 


No. FATs 


2 


2 


2 


2 


2 


2 


2 


Root directory 
entries 64 


64 


112 


112 


68 


68 


192 


No. sectors 


320 


360 


640 


720 


2002 


2002 


616 


Media Descriptor 
Byte FE 


FC 


FF 


FD 


FE* 


FD 


FE* 


Sectors for 
1 FAT 


1 


2 


1 


2 


6 


6 


2 



♦The two media descriptor bytes that are the same for 
8" disks (FEH) is not a misprint. To establish 
whether a disk is single- or double-density, a 
read of a single-density address mark should be 
made. If an error occurs, the media is double- 
density. 



CHAPTER 4 
MS-DOS CONTROL BLOCKS AND WORK AREAS 



4.1 TYPICAL MS-DOS MEMORY MAP 

0000:0000 
XXXX:0000 
XXXX:0000 



Interrupt vector table 

IO. SYS - MS-DOS interface to hardware 



MSDOS.SYS - MS-DOS interrupt handlers, 
service routines (Interrupt 21H functions) 

MS-DOS buffers, control areas, and installed 
device drivers 

XXXX:0000 Resident part of COMMAND.COM - Interrupt 
handlers for Interrupts 22H (Terminate 
Address), 23H (CONTROL-C Exit Address), 
24H (Fatal Error Abort Address) 
and code to reload the transient part 

XXXX:0000 External command or utility- (.COM or 
•EXE file) 

XXXX:0000 User stack for .COM files (256 bytes) 

XXXX:0000 Transient part of COMMAND.COM - Command 
interpreter, internal commands, batch 
processor 



1. Memory map addresses are in segment:of f set format, 
For example, 0090:0000 is absolute address 0900H. 



User memory is allocated from the lowest end of 
available memory that will meet the allocation 
request. 
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4.2 MS-DOS PROGRAM SEGMENT 

When an external command is typed, or when you execute a 
program through the EXEC system call, MS-DOS determines the 
lowest available free memory address to use as the start of 
the program. This area is called the Program Segment. 

The first 256 bytes of the Program Segment are set up by the 
EXEC system call for the program being loaded into memory. 
The program is then loaded following this block. An .EXE 
file with minalloc and maxalloc both set to zero is loaded 
as high as possible. 

At offset within the Program Segment, MS-DOS builds the 
Program Segment Prefix control block. The program returns 
from EXEC by one of four methods: 

1. A long jump to offset in the Program Segment 
Prefix 

2. By issuing an INT 20H with CS:0 pointing at the PSP 

3. By issuing an INT 21H with register AH=0 with CS:0 
pointing at the PSP, or 4CH and no restrictions on 
CS 

4. By a long call to location 50H in the Program 
Segment Prefix with AH=0 or Function Request 4CH 



NOTE 

It is the responsibility of 
all programs to ensure that 
the CS register contains the 
segment address of the Program 
Segment Prefix when 
terminating via any of these 
methods, except Function 
Request 4CH. For this reason, 
using Function Request 4CH is 
the preferred method. 



All four methods result in transferring control to the 
program that issued the EXEC. During this returning 
process, Interrupts 22H, 23H, and 24H (Terminate Address, 
CONTROL-C Exit Address, and Fatal Error Abort Address) 
addresses are restored from the values saved in the Program 
Segment Prefix of the terminating program. Control is then 
given to the terminate address. If this is a program 
returning to C0MMAND.COM, control transfers to its resident 
portion. If a batch file was in process, it is continued; 
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otherwise, COMMAND.COM performs a checksum on the transient 
part, reloads it if necessary, then issues the system prompt 
and waits for you to type the next command. 

When a program receives control, the following conditions 
are in effect: 

For all programs ; 

The segment address of the passed environment is 
contained at offset 2CH in the Program Segment 
Prefix. 

The environment is a series of ASCII strings 
(totaling less than 32K) in the form: 

NAME=parameter 

Each string is terminated by a byte of zeros, and 
the set of strings is terminated by .unother byte of 
zeros. The environment built bv the command 
processor contains at least a C0MSPEC= string (the 
parameters on COMSPEC define the path used by 
MS-DOS to locate C0MMAND.COM on disk). The last 
PATH and PROMPT commands issued will also be in the 
environment, along with any environment strings 
defined with the MS-DOS SET command. 

The environment that is passed is a copy of the 
invoking process environment. If your application 
uses a "keep process" concept, you should be aware 
that the copy of the environment passed to you is 
static. That is, it will not change even if 
subsequent SET, PATH, or PROMPT commands are 
issued . 

Offset 50H in the Program Segment Prefix contains 
code to call the MS-DOS function dispatcher. By 
placing the desired function request number in AH, 
a program can issue a far call to offset 50H to 
invoke an MS-DOS function, rather than issuing an 
Interrupt 21H. Since this is a call and not an 
interrupt, MS-DOS may place any code appropriate to 
making a system call at this position. This makes 
the process of calling the system portable. 

The Disk Transfer Address (DTA) is set to 80H 
(default DTA in the Program Segment Prefix) . 
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File control blocks at 5CH and 6CH are formatted 
from the first two parameters typed when the 
command was entered. If either parameter contained 
a pathname, then the corresponding FCB contains 
only the valid drive number. The filename field 
will not be valid. 

An unformatted parameter area at 81H contains all 
the characters typed after the command (including 
leading and imbedded delimiters), with the byte at 
80H set to the number of characters. If the <, >, 
or parameters were typed on the command line, they 
(and the filenames associated with them) will not 
appear in this area; redirection of standard input 
and output is transparent to applications. 

Offset 6 (one word) contains the number of bytes 
available in the segment. 

Register AX indicates whether or not the drive 
specifiers (entered with the first two parameters) 
are valid, as follows: 

AL=FF if the first parameter contained an 
invalid drive specifier (otherwise AL=00) 

AH=FF if the second parameter contained an 
invalid drive specifier (otherwise AH=00) 

Offset 2 (one word) contains the segment address of 
the first byte of unavailable memory. Programs 
must not modify addresses beyond this point unless 
they were obtained by allocating memory via the 
Allocate Memory system call (Function Request 48H) . 
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For Executable ( .EXE ) programs ; 

DS and ES registers are set to point to the Program 
Segment Prefix. 

CS,TP,SS, and SP registers are set to the values 
passed by MS-LINK. 



For Executable ( .COM) programs : 

All four segment registers contain the segment 
address of the initial allocation block that starts 
with the Program Segment Prefix control block. 

All of user memory is allocated to the program. If 
the program invokes another program through 
Function Request 4BH, it must first free some 
memory through the Set Block (4AH) function call, 
to provide space for the program being executed. 

The Instruction Pointer (IP) is set to 100H. 

The Stack Pointer register is set to the end of the 
program's segment. The segment size at offset 6 is 
reduced by 100H to allow for a stack of that size. 

A word of zeros is placed on top of the stack. 
This is to allow a user program to exit to 
C0MMAND.COM by doing a RET instruction last. This 
assumes, however, that the user has maintained his 
stack and code segments. 
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Figure 5 illustrates the format of the Program Segment 
Prefix. All offsets are in hexadecimal. 



(offsets in hex) 



INT 20H 



End of 
alloc, 
block* 



Reserved 



Long call to MS- 
DOS function dis- 
patcher (5 bytes)** 



Terminate address 
(IP, CS) 



10 



CTRL-C exit 
address (IP) 



CTRL-C exit 
address (CS) 



Hard error exit address 
(IP, CS) 



Used by MS-DOS *** 
2CH 

5CH 



Formatted Parameter Area 1 formatted as standard 
unopened FCB 6CH 



Formatted Parameter Area 2 formatted as standard 
unopened FCB (overlaid if FCB at 5CH is opened) 



80 



100 



Unformatted Parameter Area 
(default Disk Transfer Area) 



Figure 5. Program Segment Prefix 



IMPORTANT 



Programs must not alter any 
part of the Program Segment 
Prefix below offset 5CH . 



CHAPTER 5 
.EXE FILE STRUCTURE AND LOADING 



NOTE 

This chapter describes .EXE 
file structure and loading 
procedures for systems that 
use a version of MS-DOS that 
is lower than 2.0. For MS-DOS 
2.0 and higher, use Function 
Request 4BH, Load and Execute 
a Program, to load (or load 
and execute) an .EXE file. 



The .EXE files produced by MS-LINK consist of two parts: 
Control and relocation information 
The load module 

The control and relocation information is at the beginning 
of the file in an area called the header. The load module 
immediately follows the header. 

The header is formatted as follows. (Note that offsets are 
in hexadecimal.) 

Offset Contents 

00-01 Must contain 4DH, 5AH. 

02-03 Number of bytes contained in last page; 

this is useful in reading overlays. 

04-05 Size of the file in 512-byte pages, 

including the header. 

06-07 Number of relocation entries in table. 
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08-09 Size of the header in 16-byte paragraphs. 

This is used to locate the beginning of 
the load module in the file. 

0A-0B Minimum number of 16-byte paragraphs 

required above the end of the loaded 
program. 

0C-0D Maximum number of 16-byte paragraphs 

required above the end of the loaded 
program. If both minalloc and max- 
alloc are 0, then the program will 
be loaded as high as possible. 

0E-0F Initial value to be loaded into stack 

segment before starting program exe- 
cution. This must be adjusted by 
relocation. 

10-11 Value to be loaded into the SP register 

before starting program execution. 

12-13 Negative sum of all the words in the 

file. 

14-15 Initial value to be loaded into the IP 

register before starting program 
execution. 

16-17 Initial value to be loaded into the CS 

register before starting program 
execution. This must be adjusted by 
relocation. 

18-19 Relative byte offset from beginning of 

run file to relocation table. 

1A-1B The number of the overlay as generated by 

MS-LINK. 

The relocation table follows the formatted area described 
above. This table consists of a variable number of 
relocation items. Each relocation item contains two fields: 
a two-byte offset value, followed by a two-byte segment 
value. These two fields contain the offset into the load 
module of a word which requires modification before the 
module is given control. The following steps describe this 
process: 

1. The formatted part of the header is read into 
memory. Its size is 1BH. 
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A portion of memory is allocated depending on the 
size of the load module and the allocation numbers 
(OA-OB and OC-OD) . MS-DOS attempts to allocate 
FFFFH paragraphs. This will always fail, returning 
the size of the largest free block. If this block 
is smaller than minalloc and loadsize, then there 
will be no memory error. If this block is larger 
than maxalloc and loadsize, MS-DOS will allocate 
(maxalloc + loadsize). Otherwise, MS-DOS will 
allocate the largest free block of memory. 



3. A Program Segment Prefix is built in the lowest 
part of the allocated memory. 



The load module size is calculated by subtracting 
the header size from the file size. Offsets 04-05 
and 08-09 can be used for this calculation. The 
actual size is downward-adjusted based on the 
contents of offsets 02-03. Based on the setting of 
the high/low loader switch, an appropriate segment 
is determined at which to load the load module. 
This segment is called the start segment. 



The load module is read into memory beginning with 
the start segment. 

The relocation table items are read into a work 
area. 



Each relocation table item segment value is added 
to the start segment value. This calculated 
segment, plus the relocation item offset value, 
points to a word in the load module to which is 
added the start segment value. The result is 
placed back into the word in the load module. 



Once all relocation items have been processed, the 
SS and SP registers are set from the values in the 
header. Then, the start segment value is added to 
SS. The ES and DS registers are set to the segment 
address of the Program Segment Prefix. The start 
segment value is added to the header CS register 
value. The result, along with the header IP value, 
is the initial CS:IP to transfer to before starting 
execution of the program. 
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